Server Backup and Restore

Server Backup and Restore

BBS includes built-in tools for backing up the server itself — the database, configuration, SSH keys, and system config. This lets you recover from hardware failure, migrate to a new server, or restore a Docker container from scratch using S3.

What Gets Backed Up

Each server backup is a compressed .tar.gz archive containing:

File	Description
dump.sql	Full MySQL dump (all tables except file catalog)
env	Configuration file (APP_KEY, DB credentials, S3 keys, SMTP, etc.)
version	BBS version at time of backup
ssh-host-keys/	SSH host key pairs (prevents "host key changed" errors for agents)
sudoers/	Sudoers files for www-data privileges
cron	Scheduler cron job definition
clickhouse-file-catalog.csv	ClickHouse catalog data (only with --with-catalogs flag)

What is NOT backed up: Borg repository data (client backups). Repositories can be multi-terabyte and are already the backup. Use S3 Offsite Sync to protect repository data separately.

Critical: The APP_KEY in .env encrypts all sensitive data — repository passphrases, S3 secret keys, SMTP passwords, API tokens. Without this key, encrypted data is permanently unrecoverable.

---

Automatic Daily Backups

Daily backups run automatically via the scheduler cron job:

• Frequency: Once per day
• Location: /var/bbs/backups/
• Retention: 7 most recent backups (older ones deleted automatically)
• Format: bbs-backup-YYYY-MM-DD_HHMMSS.tar.gz

No configuration needed — automatic backups are enabled by default on every BBS installation.

---

Manual Backup

Run a backup on demand:

sudo /var/www/bbs/bin/bbs-backup

To save to a custom directory:

sudo /var/www/bbs/bin/bbs-backup /root/pre-update-backup/

Options

Flag	Description
--with-catalogs	Include ClickHouse file catalog data (can be large)
--keep N	Keep N most recent backups instead of the default 7

When to Backup Manually

• Before major version updates
• Before server migrations
• Before any configuration changes involving APP_KEY
• Before disk maintenance

---

Offsite Backup to S3

To protect against total server loss, sync your server backups to S3-compatible storage:

1. Go to Storage in the sidebar, then click S3 Sync Settings
2. Enter your S3 credentials (endpoint, region, bucket, access/secret keys)
3. Check "Sync server backups to off-site storage daily"
4. Click Save S3 Settings

Once enabled, the scheduler automatically uploads server backups to bucket/[prefix]/_server-backups/ daily after the backup completes. Only the 7 most recent backups are kept in S3.

---

Restoring from a Local Backup

Prerequisites

• A fresh BBS installation (bare metal via bbs-install, or a Docker container)
• A backup .tar.gz file (from /var/bbs/backups/ or downloaded from S3)

Bare Metal Restore

1. Install BBS on the new server:

   sudo bash bbs-install --hostname backup.example.com

2. Copy the backup file to the server:

   scp bbs-backup-2026-03-04_120000.tar.gz root@newserver:/tmp/

3. Run the restore:

   sudo /var/www/bbs/bin/bbs-restore /tmp/bbs-backup-2026-03-04_120000.tar.gz

The restore script walks through 7 steps interactively:

1. Version checkout — checks out the git tag matching the backup version
2. Restore .env — prompts before overwriting (preserves APP_KEY and encryption)
3. Import database — drops and recreates all tables from the backup dump
4. Restore SSH host keys — so agents don't see "host key changed" errors
5. Restore ClickHouse catalogs — file-level search index (if included in backup)
6. Restore system config — sudoers and cron files
7. Recreate Unix users — restores SSH users for all registered agents

After the restore, bbs-update runs automatically to fix permissions and apply any pending migrations.

Post-Restore Checklist

• Log in to the web UI and verify clients, plans, and schedules
• Check Settings — hostname, email/SMTP, S3 credentials
• Verify agent connectivity (agents should reconnect automatically)
• If the hostname changed, update agent configurations to point to the new server
• If repository data is on the same disk, verify repositories are accessible

---

Restoring from S3

If you have S3 credentials configured with "Sync server backups" enabled, you can restore directly from S3 through the web UI — no need to manually download or transfer backup files. This works on both bare metal and Docker installations.

Steps

1. Install BBS on the new server (bare metal via bbs-install, or start a fresh Docker container)
2. Log in with the initial admin credentials
3. Go to Storage → S3 Sync Settings
4. Enter the same S3 credentials used by your previous server
5. Click Save S3 Settings
6. Scroll down to the Restore from S3 Backup card
7. Click List Available Backups — you'll see all server backups stored in S3
8. Click Restore on the backup you want
9. Confirm in the warning dialog
10. BBS downloads the backup from S3, restores the database and configuration, and displays new admin credentials
11. Save the new credentials, then click Go to Login

After logging in, all your clients, repositories, backup plans, and settings from the backup will be restored. Repository data still needs to be restored separately (use the S3 Restore feature on each repository, or wait for agents to reconnect and create new backups).

Note: The restore replaces the entire database, so a new admin password is generated and displayed. The old password from the backup will not work.

What Happens During S3 Restore

• The selected backup is downloaded from S3 to a temporary directory
• bbs-restore --yes runs non-interactively: restores .env, imports the database, restores SSH keys, recreates Unix users
• Stale queued jobs from the backup are cleared (they reference repos/agents that may not exist on the new server)
• On bare metal, the code is checked out to match the backup version, then bbs-update upgrades to latest
• On Docker, the version checkout is skipped (code is baked into the image) and migrations bring the schema up to date
• If the backup's database credentials differ from the running server (e.g. restoring a bare-metal backup onto Docker), the restore automatically keeps the working credentials

---

Non-Interactive Restore

For scripted or automated restores, use the --yes flag to skip all interactive prompts:

sudo /var/www/bbs/bin/bbs-restore --yes /tmp/bbs-backup-2026-03-04_120000.tar.gz

When --yes is used:

• .env is overwritten without prompting
• Database is dropped and reimported without prompting
• A new random admin password is generated and printed to stdout as NEW_ADMIN_PASSWORD=<password>

This is what the web UI's "Restore from S3" feature uses internally.

---

Troubleshooting

Backup Fails

Check disk space:

df -h /var/bbs/backups/

Check MySQL connection:

sudo mysql -e "SHOW DATABASES;"

Restore Fails

"Could not read DB credentials from .env":

• The backup's .env file is damaged or missing credentials
• Try restoring .env manually: tar -xzf backup.tar.gz env

Database import fails:

• Check MySQL is running: sudo systemctl status mysql (or mariadb)
• Ensure the MySQL user has sufficient privileges

Version tag not found:

• The backup is from a version that doesn't have a git tag
• The restore continues with the current installed code and runs migrations

S3 Restore Shows No Backups

• Verify S3 credentials are correct (use Test Connection)
• Ensure the previous server had "Sync server backups" enabled
• Check the S3 path prefix matches what the previous server used
• Backups are stored at bucket/[prefix]/_server-backups/

Agents Show Offline After Restore

• If restoring to a new server with a different IP/hostname, agents need their server URL updated
• If restoring to the same server, agents should reconnect automatically within a few minutes
• SSH host keys are restored from the backup, so agents won't see "host key changed" errors

---

Related: S3 Offsite Sync | Docker Installation | Updating BBS | Storage Setup