Restore

restore means “put data back.”

kamal-backup has two restore destinations:

  • restore local: run on your machine, restore into your local database and local Active Storage path
  • restore production: run on production infrastructure, restore back into the live production database and production Active Storage path

That distinction is strict. local means your machine. production means the production-side accessory context.

restore local

This is the fast way to pull a production backup down into local development.

When you pass -d or -c, kamal-backup uses config/kamal-backup.yml as the production source of truth for:

  • app_name
  • database_adapter
  • restic_repository
  • local_restore_source_paths from production backup_paths

For a normal Rails app, the local targets come from Rails conventions:

  • the development database in config/database.yml
  • storage as the local Active Storage target
  • tmp/kamal-backup as the local drill state directory

You still provide the local secrets yourself in env:

  • RESTIC_PASSWORD
  • PGPASSWORD or MYSQL_PWD when needed

And you need the restic binary installed locally and available on PATH.

Example:

bundle exec kamal-backup -d production restore local latest

Without -d or -c, restore local reads from the local Rails app and env.

What it does:

  • restores the latest database backup into your current local database
  • restores the latest Active Storage file snapshot into a temporary staging directory
  • replaces the local backup paths with the restored copy

If your local targets are nonstandard, create config/kamal-backup.local.yml:

database_url: postgres://localhost/chatwithwork_development
backup_paths:
  - storage
state_dir: tmp/kamal-backup

If the production Active Storage paths differ from your local Active Storage paths and you are not using -d or -c, set LOCAL_RESTORE_SOURCE_PATHS yourself.

restore local refuses to run when RAILS_ENV, RACK_ENV, APP_ENV, or KAMAL_ENVIRONMENT is set to production unless you explicitly override that guard.

restore production

This is the emergency path: restore back into the live production database and live production Active Storage path.

From your app checkout:

bundle exec kamal-backup -d production restore production latest

That command prompts locally, then shells out through Kamal to the backup accessory and runs:

kamal-backup restore production latest --yes

If you are already inside the accessory container, you can run the command directly there too.

This path uses:

  • the accessory’s current database_url or sqlite_database_path
  • the accessory’s current backup_paths
  • the same restic repository the scheduled backups use

This is intentionally not a quiet operation. restore production is for real incident recovery.

Prompts and Safety

The safety model is:

  • you must choose local or production
  • destructive restores prompt for confirmation
  • automation must pass --yes
  • local restores refuse production-looking local targets unless you explicitly override them

That keeps the interface close to Kamal itself: explicit command, explicit target, deliberate confirmation.