Backup & Restore

YotoShelf includes backup and restore subcommands built into the binary. The database backup uses SQLite's VACUUM INTO — the server does not need to stop.

Backup

Two modes are available:

Mode	Command	Contents
Full	yotoshelf backup --output /backups/yotoshelf-$(date +%Y%m%d).tar.gz	Database + library files
DB-only	yotoshelf backup --db-only --output /backups/yotoshelf-$(date +%Y%m%d).tar.gz	Database only

The DB-only mode is useful when library files are already protected by volume snapshots (Docker volumes, ZFS, LVM). You can skip redundant archiving of large audio files while still protecting the database.

Retention

The --keep=N flag automatically removes archives older than N days from the output directory. Only files matching the yotoshelf-YYYYMMDD.tar.gz naming pattern are removed — other files in the directory are untouched.

yotoshelf backup \
  --output /backups/yotoshelf-$(date +%Y%m%d).tar.gz \
  --keep=7

Scheduled backups

Add a crontab entry to run backups automatically. The example below runs a full backup at 2 AM daily and keeps 7 days of archives:

0 2 * * * /usr/local/bin/yotoshelf backup \
  --output /backups/yotoshelf-$(date +\%Y\%m\%d).tar.gz \
  --keep=7

For Docker deployments, use docker exec to run the subcommand in the running container, or mount the backup directory into the container and run a sidecar.

Restore

Restore requires stopping the server first. The restore command validates the archive's migration version against the current binary — if the backup is from a newer version, restore is rejected. Upgrade YotoShelf before restoring in that case. Pending migrations are applied automatically after a successful restore.

# Stop the server
systemctl stop yotoshelf

# Restore (saves the current DB as .bak before replacing it)
yotoshelf restore --from /backups/yotoshelf-20260323.tar.gz

# Restart
systemctl start yotoshelf

The existing database is preserved as .bak alongside the restored file before being replaced.

What to back up

• Database — the SQLite file at YOTOSHELF_DB_PATH. This holds all cards, tracks, accounts, and settings. It is the critical file.
• Library — the directory at YOTOSHELF_LIBRARY_PATH. Audio files, cover images, and generated assets. Large but reconstructible for content already published to Yoto.

At minimum, back up the database daily. The library can be included in full backups or protected separately via volume-level snapshots.