Backups

Dubby has a built-in backup and restore system accessible from the admin UI and REST API. You can also perform manual backups using standard tools.

Built-in backup system

Creating a backup

Go to Settings > Backups in the admin panel and click Create Backup. Each backup can include any combination of components:

Component	What’s included	Size impact
Database	Full SQLite snapshot (users, metadata, settings, watch progress)	~50 MB per 1,000 items
Images	Cached TMDB artwork (posters, backdrops, logos)	1-5 GB typical
Trickplay	Seek preview thumbnail sprites	~50 MB per movie/episode

Scheduled backups

Configure automatic backups under Settings > Backups > Schedule:

• Cron schedule — Set the frequency (e.g., daily at 3 AM)
• Retention count — How many backups to keep. When the limit is exceeded, the oldest backup is deleted automatically
• Components — Choose which components to include in scheduled backups

Managing backups

From the backup list, you can:

• Download — Export a backup archive from the server for offsite storage
• Upload — Import a previously downloaded archive (with optional auto-restore)
• Restore — One-click restore from any completed backup (owner-only)
• Delete — Remove old backups to free disk space

REST API

# List backups
curl -H "Authorization: Bearer $TOKEN" http://localhost:3000/v1/backups

# Create a backup
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"components": ["database", "images"]}' \
  http://localhost:3000/v1/backups

# Restore from a backup
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"backupId": "backup-id-here"}' \
  http://localhost:3000/v1/backups/restore

Manual backup

For users who prefer external backup tools, the data directory can be backed up directly.

What to back up

Data	Location	Contains
Database	DUBBY_DATA_DIR/dubby.db	Users, libraries, metadata, watch progress, settings
WAL files	DUBBY_DATA_DIR/dubby.db-wal, dubby.db-shm	Uncommitted database transactions
Image cache	DUBBY_METADATA_CACHE_DIR	Cached TMDB artwork
Trickplay sprites	DUBBY_TRICKPLAY_CACHE_DIR	Seek preview thumbnails

What you can skip

• Transcode cache — Temporary files, regenerated on demand
• Log files — Useful for debugging but not critical
• Media files — Back these up separately; Dubby doesn’t modify your media

Hot backup (without stopping)

SQLite in WAL mode supports concurrent reads during writes. You can copy the database while the server is running:

sqlite3 /path/to/dubby-data/dubby.db ".backup '/path/to/backup/dubby.db'"

The .backup command creates a consistent snapshot even while the database is in use.

External cron job

If you prefer to manage backups outside of Dubby:

/etc/cron.d/dubby-backup

0 3 * * * root sqlite3 /path/to/dubby-data/dubby.db ".backup '/backups/dubby-$(date +\%Y\%m\%d).db'" && find /backups -name "dubby-*.db" -mtime +7 -delete

Docker volume backup

If using Docker named volumes:

docker run --rm \
  -v dubby-data:/data:ro \
  -v /path/to/backups:/backup \
  alpine tar czf /backup/dubby-data-$(date +%Y%m%d).tar.gz -C /data .

Restoring manually

1. Stop the server: docker compose stop dubby
2. Replace the data directory with the backup
3. Start the server: docker compose start dubby

The server checks for pending migrations on startup and applies them if needed.

What’s preserved in a backup

• All user accounts and sessions
• Library configurations and paths
• All metadata (titles, descriptions, artwork references)
• Watch progress and continue watching state
• User preferences and settings
• Feature flag configurations
• Collections and watchlists
• AI enrichment data
• Parental control profiles
• Invite codes and permissions

What’s not preserved

• Active streaming sessions (ephemeral)
• Cached transcodes (regenerated on demand)
• Trickplay sprites (unless included in the backup components)