Back up and restore an instance

A backup saves everything on your Savorum server in one file: recipes, photos, books, tags, history, and the original files you kept from imports. Make one regularly, keep a copy somewhere else, and practice a restore now and then so you know it works.

Run these commands as the system user that owns the database and assets folder. If savorum isn’t on your PATH, use its full path, such as ./bin/savorum.

Make and check a backup

Never copy the live .db file to make a backup. A copy taken while Savorum runs can be incomplete. Use the backup command, which is safe while Savorum is running.

1. Back up to a folder outside Savorum’s data folder, then verify the file:

   savorum backup \
     --database /var/lib/savorum/savorum.db \
     --assets /var/lib/savorum/assets \
     --output /var/backups/savorum/instance.savorum-backup
   
   savorum verify --input /var/backups/savorum/instance.savorum-backup

2. Copy the backup somewhere else, such as another disk or a cloud drive, and run savorum verify on the copy.

3. Every so often, practice a restore.

verify checks that the file is complete and undamaged, and that this version of Savorum can restore it. It doesn’t change your running server. Verify with the same version you’ll restore with.

Checksums catch damage, not tampering. Verifying finds a corrupted backup, but can’t tell who made it. Someone who can replace a backup can replace its checksums too. Protect where you store backups, and only restore one you trust.

Encrypted backups

Add --encrypt to seal the backup, and your webhook signing keys, in one password-protected file. Savorum asks for the password twice, or reads it from --password-file FILE (- reads standard input), which also turns on encryption:

savorum backup \
  --database /var/lib/savorum/savorum.db \
  --assets /var/lib/savorum/assets \
  --encrypt \
  --output /var/backups/savorum/instance.savorum-backup.age

verify and restore ask for the password, or read it from --password-file. The file is an age file, so the standard age tool can decrypt it too.

The password can’t be recovered. Without it, the backup is lost. Keep it as safely as the backup itself.

Restore a backup

Restore replaces everything on the target server. Don’t merge restored files into a current assets folder, and don’t use a full backup to bring back selected recipes.

1. Stop Savorum, using whatever normally runs it.

2. Verify the backup with the same version of Savorum that will run it.

3. Restore it:

   savorum restore --input /var/backups/savorum/instance.savorum-backup \
     --database /var/lib/savorum/savorum.db --assets /var/lib/savorum/assets

4. Start Savorum. Open a few recipes and books, check history and the trash, and load some photos.

An encrypted restore also puts back the webhook signing keys. It refuses if <database>.webhook-secrets already holds keys.

Restore a Compose deployment

Mount the backup folder read-only, and use the same data volume and paths as the service:

docker compose stop savorum
docker compose run --rm --no-deps \
  -v /var/backups/savorum:/backups:ro \
  savorum verify --input /backups/instance.savorum-backup
docker compose run --rm --no-deps \
  -v /var/backups/savorum:/backups:ro \
  savorum restore --input /backups/instance.savorum-backup \
    --database /data/savorum.db --assets /data/assets
docker compose up -d savorum

Don’t restore inside a running container.

Practice a restore

Restore into a new, empty folder or volume, so your real server isn’t touched. With the source build:

./bin/savorum backup \
  --database ./data/savorum.db \
  --assets ./data/assets \
  --output ./data/instance.savorum-backup
./bin/savorum verify --input ./data/instance.savorum-backup
install -d -m 700 ./restore-data
./bin/savorum restore \
  --input ./data/instance.savorum-backup \
  --database ./restore-data/savorum.db \
  --assets ./restore-data/assets
./bin/savorum check-database --database ./restore-data/savorum.db

Write down the backup date, the Savorum version, how long it took, and what you checked.

Move from Savorum Cloud

Savorum Cloud gives the library owner a download in the encrypted backup format. To move it to your own server:

1. Restore the download with its password. This also installs its webhook signing keys.
2. Run hosting show and note the owner_user_id it prints.
3. Give the owner a local password. Leave out --login if the account already has a local login.
4. Release the hosting link. This needs the password from step 3.

savorum restore --input library.savorum-backup.age \
  --database /data/savorum.db --assets /data/assets
savorum hosting show --database /data/savorum.db
savorum user reset-password --database /data/savorum.db \
  --user-id OWNER_ID --login owner
savorum hosting release --database /data/savorum.db

Releasing turns off the Cloud sign-in and signs out its sessions and tokens. Your recipes, libraries, and roles stay. Then remove the Cloud provider from your provider file if you copied one, set --public-url to your own address, and start Savorum with --auth-enabled.

Passkeys stay tied to the old address, so they stop working. Sign in with the password, then add new passkeys.

Good to know

• Webhook signing keys, in the <database>.webhook-secrets folder beside the database, aren’t in a plain backup. Back them up separately with the same care, use an encrypted backup, or replace every webhook secret after a restore.
• Resized photos aren’t in the backup; Savorum makes them again. Temporary job files aren’t backed up.
• Backup refuses to start unless the destination has room for about twice the database, plus all original files, plus 512 MiB. savorum storage --backup-directory DIR shows the expected size and free space.
• Verify and restore need free space of about three times the database, plus the original files.
• A backup holds the database’s write lock while it copies, so run a large backup at a quiet time.
• Encrypting or decrypting needs about 528 MiB of free memory. A server with 512 MiB refuses before writing anything. Plain backups still work there; open encrypted ones on a machine with more memory.
• verify and restore accept at most 64 GiB of uncompressed content. For a larger backup you trust, add --max-expanded-bytes BYTES to both, such as --max-expanded-bytes 137438953472.
• Backup files are readable only by their owner (0600). Never make them world-readable. If your server uses group storage, set SAVORUM_STORAGE_ACCESS=group for every backup and restore too.
• If a restore is interrupted, start Savorum normally with the same paths so it can finish recovering. Never delete the lock file, recovery journal, SQLite -wal or -shm files, or older copies to force it to start.

Next: Configure an instance.