Backup & Restore

Holden is stateless — it has no database. But you still need to back up two directories.

What to Back Up

/data (Critical)

The /data directory contains:

• age.key — Decrypts secrets in your holden.vars.yml files
• password_seed — Derives database passwords for needs containers
• apps.yml — App registrations

If you lose /data:

• Encrypted secrets become unreadable
• Database passwords change, breaking existing data
• App registrations need to be re-added via holden app add

Back this up securely. It’s small (a few KB) and rarely changes.

backup_dir (App Data)

The backup_dir directory (e.g. /mnt/backups) contains consistent, point-in-time snapshots created during the maintenance window. Containers are stopped before backup, so database files are never copied mid-write.

Back this directory up off-site as frequently as your RPO requires. See Offsite Sync for examples.

Caution

Don’t back up HOLDEN_BASE_DATA_DIR directly — it contains live data that may be mid-write. The maintenance backups in backup_dir are the consistent copies you want.

Restoring Holden

If you need to restore from scratch:

1. Restore /data — Copy your backed-up data directory
2. Restore app data — Copy the latest backup for each app from backup_dir into HOLDEN_BASE_DATA_DIR
3. Start Holden — It reads apps.yml and recreates all containers

Since passwords are derived from the seed in /data/password_seed, databases reconnect automatically.

Restoring a Single App

To restore an app from a maintenance backup:

1. Remove the app from your config (Holden stops its containers)
2. Copy backup data over the app’s data directory in base_data_dir
3. Add the app back to config (Holden starts it with restored data)

Git is Your Config Backup

Your app configuration lives in git (each app’s holden.yml and holden.vars.yml). To “restore” your config, just re-register your apps with holden app add.

Host settings are environment variables on the Holden container — keep these in your docker-compose or deployment tool.