# kamal-backup Documentation — Full Documentation

> Documentation for kamal-backup, an open-source Ruby gem and Kamal accessory for scheduled Rails database and file-backed Active Storage backups, restores, drills, and security-review evidence.

---

# kamal-backup Documentation

Canonical URL: https://kamal-backup.dev/

Add scheduled, encrypted backups to Rails apps deployed with Kamal: database dumps, Active Storage files, restore drills, and review evidence.

---

# Getting Started

Canonical URL: https://kamal-backup.dev/getting-started/

Run `kamal-backup init`, fill in one config file, add one Kamal accessory, then boot it. The accessory runs scheduled database and Active Storage backups from there.

This guide assumes:

- you already deploy the app with Kamal;
- your database is PostgreSQL, MySQL/MariaDB, or SQLite;
- file-backed Active Storage files are available on a mounted path such as `/data/storage`.

In normal Kamal use, restic runs inside the backup accessory image. You do not install restic on the Rails app host.

## 1. Add the gem

In the Rails app:

```ruby
group :development do
  gem "kamal-backup"
end
```
{: data-title="Gemfile"}

Then install it and generate the config file:

```sh
bundle install
bundle exec kamal-backup init
```

That creates `config/kamal-backup.yml`. Put the production backup settings in that file:

```yaml
app: chatwithwork
accessory: backup
databases:
  - name: app
    adapter: postgres
    url: postgres://chatwithwork@chatwithwork-db:5432/chatwithwork_production
    password:
      secret: DATABASE_PASSWORD
paths:
  - /data/storage
restic:
  repository: s3:https://s3.example.com/chatwithwork-backups
  password:
    secret: RESTIC_PASSWORD
  init_if_missing: true
backup:
  schedule: 1d
```
{: data-title="config/kamal-backup.yml"}

File backups are opt-in: only paths explicitly listed under `paths` are included. `kamal-backup` never infers `storage` from Rails. For local restores, Rails can still provide the development database and `tmp/kamal-backup`; when production file paths are configured, list their local targets in `config/kamal-backup.local.yml`.

## 2. Choose where backups live

Before you boot the accessory, decide where the encrypted restic repository will live. Common choices are:

- S3-compatible object storage;
- an SFTP server reached with a dedicated SSH key;
- any configured rclone remote;
- a restic REST server you run separately;
- a filesystem path for local development.

`kamal-backup` chooses restic because it gives Rails teams encrypted snapshots, deduplication, retention, repository checks, and a portable restore format without inventing a new backup backend. It does not manage the repository service for you.

## 3. Add the accessory

Add a backup accessory to your Kamal deploy config:

```yaml
accessories:
  backup:
    image: ghcr.io/crmne/kamal-backup:latest
    host: chatwithwork.com
    files:
      - config/kamal-backup.yml:/app/config/kamal-backup.yml:ro
    env:
      secret:
        - DATABASE_PASSWORD
        - RESTIC_PASSWORD
        - AWS_ACCESS_KEY_ID
        - AWS_SECRET_ACCESS_KEY
    volumes:
      - "chatwithwork_storage:/data/storage"
      - "chatwithwork_backup_state:/var/lib/kamal-backup"
```
{: data-title="config/deploy.yml"}

Kamal uploads `config/kamal-backup.yml` and mounts it read-only into the accessory. Secrets still stay in Kamal secrets.

The storage volume is writable so `restore production` can replace its contents without replacing the mount point.
Writable access is also required when a live SQLite database is stored on that volume. For a backup-only accessory,
you can append `:ro`; remove it and reboot the accessory before a production file restore.

## 4. Boot the accessory

```sh
bundle exec kamal-backup validate
bin/kamal accessory boot backup
bin/kamal accessory logs backup
```

`validate` catches missing required backup settings before the accessory has to be running.

The container default command is `kamal-backup schedule`, so once the accessory is up it starts running scheduled backups. In the example above, `backup.schedule: 1d` means one backup per day.

The `/var/lib/kamal-backup` volume preserves the latest `check` and restore drill records across accessory reboots. Keep it mounted if you want `kamal-backup evidence` to include recent operational proof after the container is recreated.

When you update the local gem, production-side commands expect the accessory to be on the same `kamal-backup` version. If they drift, reboot the accessory so it pulls the current `latest` image:

```sh
bin/kamal accessory reboot backup
```

## 5. Run and inspect the first backup

From your app checkout, use the gem and let it shell out through Kamal:

```sh
bundle exec kamal-backup backup
bundle exec kamal-backup list
bundle exec kamal-backup evidence
```

`backup` respects the configured schedule and tells you when no backup is due. Use `bundle exec kamal-backup backup --force` to create an immediate snapshot.

With the default `config/deploy.yml`, `backup`, `list`, `check`, `unlock`, `evidence`, `validate`, and `version` infer the backup accessory. If you keep multiple deploy configs or destinations, pass `-c` or `-d` the same way Kamal does:

```sh
bundle exec kamal-backup -c config/deploy.staging.yml -d staging backup
```

The same pattern works for the other production-side commands:

```sh
bundle exec kamal-backup check
bundle exec kamal-backup unlock
bundle exec kamal-backup validate
bundle exec kamal-backup version
bundle exec kamal-backup -d production schedule
```

`kamal-backup version` is a quick diagnostic: it reads `config/deploy.yml`, checks the backup accessory version, and tells you whether the local gem and remote accessory are in sync.

## What the first backup creates

Each backup run creates:

- one restic stdin snapshot for each configured database;
- one `type:files` restic snapshot for the configured paths.

Database dump snapshots are tagged with `kamal-backup`, `app:<name>`, `type:database`, `database:<name>`, and `adapter:<adapter>`. File snapshots use `type:files` plus informational `path:<label>` tags for the configured paths. Restic stores the snapshot time separately.

The next useful step is a restore drill:

Local restore and drill commands need the `restic` binary installed on your machine. Production-side commands use the backup accessory image, which already includes it.

```sh
bundle exec kamal-backup -d production drill local latest --check "bin/rails runner 'puts User.count'"
bundle exec kamal-backup -d production evidence
```

That gives you a backup, a restore proof, and a redacted evidence packet for a security review like CASA.

---

# How Backups Work

Canonical URL: https://kamal-backup.dev/how-backups-work/

## The model

`kamal-backup` runs as a Kamal accessory. In normal production use, the accessory runs `kamal-backup schedule`, wakes up on the configured interval, and creates one snapshot per configured database plus one file snapshot for configured paths.

The goal is simple: scheduled backups for Rails apps deployed with Kamal that are easy to restore, easy to drill, and easy to explain in a security review.

## Why restic

`kamal-backup` uses [restic](https://restic.net/) as the backup engine and repository format.

Restic is the right backend here because it provides:

- encrypted repositories by default;
- snapshots with stable tags, so database and file backups can be selected independently;
- deduplication across repeated backup runs;
- retention and prune commands;
- repository health checks;
- Restic's native repository backends plus rclone remotes; the accessory includes rclone and an SSH client.

That lets `kamal-backup` stay Rails- and Kamal-focused instead of inventing a custom backup format.

In normal Kamal use, you do not install restic on the Rails app host. The backup accessory image already contains the `restic` binary. You point that accessory at a restic repository, usually:

- S3-compatible object storage;
- an SFTP server reached with a dedicated SSH key;
- any configured rclone remote;
- a restic REST server;
- a filesystem path for local development.

If you choose a `rest:` repository, `kamal-backup` does not install or run that server for you. It is a separate service you operate yourself.

## What happens during a backup

When a backup run starts, `kamal-backup` does five things:

1. It validates the app name, restic repository, database settings, and file paths.
2. It creates database backups using the database-native export tool:
   PostgreSQL uses `pg_dump`, MySQL/MariaDB use `mariadb-dump` or `mysqldump`, and SQLite uses `sqlite3 .backup`.
3. It has restic run and capture each database export, then tags the snapshot with `type:database`,
   `database:<name>`, and `adapter:<adapter>`. If the export command fails, restic does not create a snapshot.
4. When `paths` is explicitly configured, it runs one `restic backup` for those paths and tags that snapshot with `type:files`. Path-level excludes and automatic SQLite database/WAL/SHM excludes apply only to this file snapshot.
5. It optionally prunes old snapshots and runs the same repository verification as `kamal-backup check`, depending on configuration.

The result is one database snapshot per database and, when paths are configured, one file snapshot per run. No file path is inferred from Rails.

## What gets backed up

`kamal-backup` is built for two data surfaces:

- your app database: PostgreSQL, MySQL/MariaDB, or SQLite;
- file-backed Active Storage files that live on mounted volumes.

If your Rails app already stores Active Storage blobs directly in S3, there may be no mounted file path to capture. In that case, `kamal-backup` still covers the database side, but S3 object backup and retention are a separate concern.

For SQLite apps that store the database under the same mounted volume as Active Storage, the database is backed up through `sqlite3 .backup`; the raw SQLite database, WAL, and shared-memory files are excluded from the file snapshot so a full restore does not overwrite the clean SQLite restore with live raw files.

## What the commands mean

- `schedule`: Run the foreground scheduler loop. This is the default accessory command.
- `backup`: Create one new snapshot per configured database and, when paths are configured, one file snapshot immediately.
- `restore local`: Pull the latest backup from restic onto your machine and restore it into your local development database and explicitly configured local file paths.
- `restore production`: Restore a backup back into the production database and production Active Storage path.
- `drill local`: Run a local restore plus an optional verification command, then record the result as JSON.
- `drill production`: Restore into a scratch database and scratch Active Storage path on production infrastructure, run an optional verification command, and record the result as JSON.
- `list`: Show restic snapshots for this app so you can see recent runs and snapshot IDs.
- `check`: Verify the restic repository and store the latest result in `KAMAL_BACKUP_STATE_DIR`, which defaults to `/var/lib/kamal-backup`.
- `unlock`: Clear stale restic repository locks.
- `prune`: Apply the configured retention policy and remove unneeded restic data.
- `evidence`: Print a redacted JSON summary with current backup settings, latest snapshots, latest check result, latest drill result, and tool versions. This is meant to be attached to internal ops records or security reviews.
- `validate`: Check required backup configuration without running a backup. From an app checkout with `config/deploy.yml`, it validates the backup accessory and `config/kamal-backup.yml` before the accessory has to be running.

## Snapshot tags

Database snapshots are tagged with:

- `kamal-backup`
- `app:<name>`
- `type:database`
- `database:<name>`
- `adapter:<adapter>`

Active Storage file snapshots are tagged with:

- `kamal-backup`
- `app:<name>`
- `type:files`
- `path:<label>` for each configured Active Storage path

Restic records each snapshot's time, so backup timestamps come from the repository metadata rather than a per-run tag.

---

# Configuration

Canonical URL: https://kamal-backup.dev/configuration/

## Generate the backup config

Run:

```sh
bundle exec kamal-backup init
```

`init` creates `config/kamal-backup.yml` if it is missing, then prints the accessory block to add to `config/deploy.yml`. It does not edit `config/deploy.yml`, and it does not create `config/kamal-backup.local.yml`.

The generated backup config looks like this:

```yaml
app: your-app
accessory: backup
databases:
  - name: app
    adapter: postgres
    url: postgres://your-app@your-db:5432/your_app_production
    password:
      secret: DATABASE_PASSWORD
paths:
  - /data/storage
restic:
  repository: s3:https://s3.example.com/your-app-backups
  password:
    secret: RESTIC_PASSWORD
  init_if_missing: true
backup:
  schedule: 1d
```
{: data-title="config/kamal-backup.yml"}

Edit that file for production. It is the main backup configuration: app name, database sources, restic repository, file paths, and schedule.

File backups are opt-in. `kamal-backup` snapshots files only when `paths` is explicitly configured; it never infers `storage` or another file path from Rails. Omit `paths` (or set `paths: []`) for a database-only backup.

`kamal-backup.yml` uses the grouped shape shown above. Older flat YAML keys such as `database_adapter`, `backup_paths`, and `restic_repository` are rejected so configuration stays explicit. See [Upgrading](/upgrading/) when moving from 0.2.

## Default options

- `accessory`: the Kamal accessory name. The default is `backup`.
- `app`: the app tag used on restic snapshots.
- `databases`: one or more PostgreSQL, MySQL/MariaDB, or SQLite databases to back up.
- `paths`: optional filesystem paths to snapshot from mounted volumes. Entries can be strings or mappings with `path` and `exclude`. No files are backed up when this is omitted or empty.
- `restic.repository`: the restic repository location, such as S3-compatible storage, SFTP, rclone, a restic REST server, or a filesystem path.
- `restic.password.secret`: the Kamal secret env var that contains the restic password.
- `restic.rest.username` and `restic.rest.password`: optional restic REST server credentials. These become `RESTIC_REST_USERNAME` and `RESTIC_REST_PASSWORD`.
- `restic.init_if_missing`: run `restic init` when the repository has not been initialized yet.
- `backup.schedule`: how often the accessory runs backups. `1d` means once per day.
- `backup.enabled`: whether the accessory takes scheduled backups. Defaults to `true`. Set it to `false` to bring an accessory up that can restore, list and check, but will never write a backup of its own. See [Migrating to a new host](/migrating-hosts/).

For MySQL, change the database settings:

```yaml
databases:
  - name: app
    adapter: mysql
    url: mysql2://app@app-mysql:3306/app_production
    password:
      secret: DATABASE_PASSWORD
```
{: data-title="config/kamal-backup.yml"}

For SQLite, point at the database file inside the accessory:

```yaml
databases:
  - name: app
    adapter: sqlite
    path: /data/storage/production.sqlite3
```
{: data-title="config/kamal-backup.yml"}

That path should be the live SQLite database file as mounted into the backup accessory. The SQLite adapter creates its own temporary backup file before sending it to restic.

When a configured SQLite database file lives under a configured file backup path, `kamal-backup` automatically excludes that database file plus its `-wal` and `-shm` sidecar files from the restic file snapshot. The SQLite database backup still runs separately through `sqlite3 .backup`.

You can also declare path-level excludes explicitly. These only apply to the restic file backup, not to database dump backups:

```yaml
databases:
  - name: app
    adapter: sqlite
    path: /rails/storage/production.sqlite3
paths:
  - path: /rails/storage
    exclude:
      - /rails/storage/*.sqlite3
      - /rails/storage/*.sqlite3-wal
      - /rails/storage/*.sqlite3-shm
```
{: data-title="config/kamal-backup.yml"}

For a live SQLite database in WAL mode, mount the storage volume read-write in the backup accessory so SQLite can open the database, WAL, and shared-memory files normally:

```yaml
volumes:
  - "your_app_storage:/data/storage"
  - "your_app_backup_state:/var/lib/kamal-backup"
```
{: data-title="config/deploy.yml"}

If you require the backup accessory to have no write access to app storage, do not point it at a live WAL database over a read-only mount. Have the writer create a WAL-less snapshot, then point the SQLite database `path` at that snapshot. That is an advanced hardening tradeoff, not the normal SQLite setup.

## Add the accessory

Copy the accessory block printed by `init` into your Kamal deploy config, then mount the generated backup config with `files:`.

```yaml
accessories:
  backup:
    image: ghcr.io/crmne/kamal-backup:latest
    host: chatwithwork.com
    files:
      - config/kamal-backup.yml:/app/config/kamal-backup.yml:ro
    env:
      secret:
        - DATABASE_PASSWORD
        - RESTIC_PASSWORD
        - AWS_ACCESS_KEY_ID
        - AWS_SECRET_ACCESS_KEY
    volumes:
      - "chatwithwork_storage:/data/storage"
      - "chatwithwork_backup_state:/var/lib/kamal-backup"
```
{: data-title="config/deploy.yml"}

The `files:` line is what keeps non-secret backup settings out of environment variables. Kamal uploads `config/kamal-backup.yml` and mounts it read-only into the accessory.
The storage volume is writable so production file restores and live SQLite WAL backups can work. For a backup-only
accessory, append `:ro`; remove it and reboot the accessory before running `restore production`.

## Secrets

Keep secrets in Kamal secrets:

```sh
RESTIC_PASSWORD=...
DATABASE_PASSWORD=...
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
```

If the repository URL contains credentials, declare it as a secret reference instead:

```yaml
restic:
  repository:
    secret: RESTIC_REPOSITORY
```
{: data-title="config/kamal-backup.yml"}

For a restic REST server, prefer keeping credentials out of the repository URL:

```yaml
restic:
  repository: rest:https://backup.example.com/prod
  rest:
    username:
      secret: RESTIC_REST_USER
    password:
      secret: RESTIC_REST_PASSWORD
```
{: data-title="config/kamal-backup.yml"}

## Repository backends

The accessory passes restic's supported backend environment variables through to restic. Choose the repository
prefix and supply its credentials as Kamal secrets:

| Repository | Prefix or form | Typical configuration |
| --- | --- | --- |
| Filesystem | `/path/to/repository` | Mount persistent storage at that path. |
| REST server | `rest:https://…` | `RESTIC_REST_USERNAME`, `RESTIC_REST_PASSWORD` |
| S3-compatible | `s3:https://…` or `s3:region:bucket` | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` |
| SFTP | `sftp:user@host:/path` | Dedicated SSH key and verified `known_hosts` |
| Backblaze B2 | `b2:bucket:path` | `B2_ACCOUNT_ID`, `B2_ACCOUNT_KEY` |
| Azure Blob Storage | `azure:container:/path` | The applicable `AZURE_*` variables |
| Google Cloud Storage | `gs:bucket:/path` | The applicable `GOOGLE_*` variables |
| OpenStack Swift | `swift:container:/path` | The applicable `OS_*`, `ST_*`, or `HP_*` variables |
| rclone | `rclone:remote:path` | An rclone config file or `RCLONE_CONFIG_<REMOTE>_*` variables |

Consult [restic's repository guide](https://restic.readthedocs.io/en/v0.18.1/030_preparing_a_new_repo.html)
for the backend-specific variables. Never put credentials directly in `config/kamal-backup.yml`.

## Rclone repositories

The accessory includes rclone, and restic officially supports using it to reach services outside restic's native
backends. Once a remote named `archive` works in rclone, use it directly:

```yaml
restic:
  repository: rclone:archive:kamal-backup/your-app
  password:
    secret: RESTIC_PASSWORD
```
{: data-title="config/kamal-backup.yml"}

For an existing rclone config, mount only that file and tell rclone where it is:

```yaml
accessories:
  backup:
    env:
      clear:
        RCLONE_CONFIG: /run/kamal-backup/rclone.conf
      secret:
        - RCLONE_CONFIG_PASS
    volumes:
      - "/etc/kamal-backup/rclone.conf:/run/kamal-backup/rclone.conf:ro"
```
{: data-title="config/deploy.yml"}

`RCLONE_CONFIG_PASS` is needed only when the config file is encrypted. Keep the config file outside the app
repository when it contains tokens or credentials. You can instead configure a remote entirely through Kamal env,
using rclone's `RCLONE_CONFIG_<REMOTE>_TYPE` and backend-specific variables; `kamal-backup` passes every
`RCLONE_*` variable through to restic and redacts secret values in its own output.

Restic starts and stops `rclone serve restic --stdio` itself—do not run a separate rclone daemon. See restic's
[rclone backend documentation](https://restic.readthedocs.io/en/v0.18.1/030_preparing_a_new_repo.html#other-services-via-rclone)
and the official [rclone backend announcement](https://restic.net/blog/2018-04-01/rclone-backend/).

## SFTP repositories

The accessory image includes an SSH client, so restic can use an SFTP repository:

```yaml
restic:
  repository: sftp:backup@backups.example.com:/srv/restic/your-app
  password:
    secret: RESTIC_PASSWORD
```
{: data-title="config/kamal-backup.yml"}

Restic's SFTP backend needs non-interactive SSH authentication. Create a dedicated key for this accessory, authorize
its public key for a restricted account on the repository host, and bind-mount only that private key and a verified
`known_hosts` file:

```yaml
accessories:
  backup:
    volumes:
      - "/etc/kamal-backup/ssh/id_ed25519:/root/.ssh/id_ed25519:ro"
      - "/etc/kamal-backup/ssh/known_hosts:/root/.ssh/known_hosts:ro"
```
{: data-title="config/deploy.yml"}

Create those files on every Kamal host that can run the accessory, and verify the repository host's fingerprint before
adding it to `known_hosts`. Do not mount the Kamal host's entire `.ssh` directory: a dedicated key limits what a
compromised accessory can reach. SSH authentication setup and key rotation remain the operator's responsibility.

`RESTIC_PASSWORD` encrypts the restic repository; it is not the SSH account password. Password-prompt authentication
is unsuitable for unattended backups, so the image does not include `sshpass`.

If you do not want the restic password value in the process environment, point restic at a mounted file instead:

```yaml
restic:
  password:
    file: /run/secrets/restic-password
```
{: data-title="config/kamal-backup.yml"}

The same works for the repository string when needed:

```yaml
restic:
  repository_file: /run/secrets/restic-repository
```
{: data-title="config/kamal-backup.yml"}

## Validate before boot

Run this before booting or rebooting the accessory:

```sh
bundle exec kamal-backup validate
```

With a normal `config/deploy.yml`, `validate` checks the backup accessory config before the accessory has to be running. It catches missing app, database, and restic settings, invalid configured backup paths, and required Kamal secrets that resolve to empty values.

## Local restores

`restore local` and `drill local` infer:

- production source settings from `config/kamal-backup.yml`
- local database settings from `config/database.yml`
- local state under `tmp/kamal-backup`

File paths are never inferred. If production `paths` are configured, add `config/kamal-backup.local.yml` with the local targets in the same order. Database-only backups do not need local file paths.

```yaml
databases:
  - name: app
    adapter: postgres
    url: postgres://localhost/chatwithwork_development
paths:
  - storage
state:
  path: tmp/kamal-backup
```
{: data-title="config/kamal-backup.local.yml"}

## Useful options

These options are supported but not included in the generated default config:

```yaml
restic:
  check_after_backup: true
  check_read_data_subset: 5%
  forget_after_backup: true
  retention:
    keep_last: 7
    keep_daily: 7
    keep_weekly: 4
    keep_monthly: 6
    keep_yearly: 2
```
{: data-title="config/kamal-backup.yml"}

`restic.forget_after_backup` defaults to enabled unless explicitly set to a falsey value such as `false`, `0`, `no`, `n`, or `off`.

You can also apply the same retention policy manually with `kamal-backup prune`. Pruning runs `restic forget --prune` for each configured database and file snapshot group, so database snapshots and file snapshots retain their own history. If a stale lock blocks prune, run `kamal-backup unlock`, then retry.

Environment variables can still override YAML values when you need an emergency override, but the clean setup is YAML for configuration and Kamal secrets for secrets.

---

# Restore

Canonical URL: https://kamal-backup.dev/restore/

Use `restore local` to inspect production data safely on your machine, and `restore production` only for deliberate incident recovery.

`restore production` replaces the target database rather than layering a dump over whatever is already there:

- PostgreSQL removes every non-system schema, recreates `public`, then restores with a client matching server majors 14–18.
- MySQL/MariaDB removes existing views, tables, MariaDB sequences, routines, and events before importing the dump.
- SQLite validates the downloaded backup, replaces the live database through SQLite's backup API, then checks the restored database again.

For PostgreSQL, resetting the user schemas avoids a common failure mode: `pg_restore --clean` issues one `DROP` per object,
but target-only foreign keys can prevent those drops, after which creates and data loads fail. This is the norm on a
fresh Kamal host because the application commonly runs `db:prepare` before the restore.

If `pg_restore` reports ignored errors, the restore fails loudly rather than exiting successfully with a partially populated database.

`kamal-backup` has two restore destinations:

- `restore local`: run on your machine, restore into your local database and explicitly configured local file paths
- `restore production`: run on production infrastructure, restore back into the live production database and configured production file paths

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`
- the first configured database adapter
- `restic.repository`
- production file paths as local restore source paths

For a normal Rails app, Rails conventions provide:

- the development database in `config/database.yml`
- `tmp/kamal-backup` as the local drill state directory

File paths are never inferred. If production has configured `paths`, create `config/kamal-backup.local.yml` and list the corresponding local targets in the same order:

```yaml
paths:
  - storage
```
{: data-title="config/kamal-backup.local.yml"}

If production has no configured paths, the command restores only the database.

You still provide the local secrets yourself in env:

- `RESTIC_PASSWORD`
- the database password env vars declared in your local config, or `PGPASSWORD`/`MYSQL_PWD` when using env-only settings

And you need the `restic` binary installed locally and available on `PATH`.
If the repository uses the `rclone:` backend, rclone must also be installed and configured on your machine.

Example:

```sh
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
- when paths are configured, restores the latest file snapshot into a temporary staging directory
- replaces the explicitly configured local paths with the restored copy

You can also configure local database and state targets in `config/kamal-backup.local.yml`:

```yaml
databases:
  - name: app
    adapter: postgres
    url: postgres://localhost/chatwithwork_development
paths:
  - storage
state:
  path: tmp/kamal-backup
```
{: data-title="config/kamal-backup.local.yml"}

If the production file paths differ from your local file paths and you are not using `-d` or `-c`, set `restore_from` in the local config.

`restore local` refuses to run when `RAILS_ENV`, `RACK_ENV`, `APP_ENV`, or `KAMAL_ENVIRONMENT` is set to `production`.

## `restore production`

This is the emergency path: restore back into the live production database and explicitly configured production file paths.

Stop the application, job workers, and every other database or SQLite writer before restoring, and keep them stopped
until the restore succeeds. PostgreSQL and MySQL restores intentionally reset existing objects; SQLite refuses a
restore when another writer holds the database lock. A typical sequence is:

```sh
bin/kamal app stop -d production
bundle exec kamal-backup -d production restore production latest
bin/kamal deploy -d production
```

Use the commands appropriate to your destination, but preserve that stop → restore → verify → start order.

From your app checkout:

```sh
bundle exec kamal-backup -d production restore production latest
```

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

```sh
kamal-backup restore production latest --confirm-production-restore
```

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

This path uses:

- the accessory's current configured databases
- the accessory's current paths
- the same restic repository the scheduled backups use

The storage volume must be mounted read-write for a production file restore. The restore replaces the contents of
an existing mounted directory while preserving the mount point itself, then restores databases. Restoring files
first prevents a failed or read-only file restore from leaving the database at a different point in time.

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

`restore production` does not accept `--yes` as a confirmation shortcut. Interactive use asks you to type the app name and `RESTORE PRODUCTION`. Automation must pass the explicit `--confirm-production-restore` flag.

The accessory image selects PostgreSQL 14, 15, 16, 17, or 18 client tools to match the target server. A local
PostgreSQL restore uses the tools installed on your machine; install a client matching the local target's major
version. Restores require privileges to replace the target schema or database objects.
MySQL/MariaDB restores that contain routines, triggers, or events also require the corresponding database privileges;
MySQL servers with binary logging may require `log_bin_trust_function_creators=1` or an administrative restore user.

## Validated database versions

The automated restore matrix exercises exact backup and restore behavior against:

| Database | Versions |
| --- | --- |
| PostgreSQL | 14, 15, 16, 17, and 18 |
| MySQL | 8.0 and 8.4 (LTS) |
| MariaDB | 10.11, 11.4, and 11.8 LTS |
| SQLite | The SQLite client shipped in the accessory image, including WAL-mode databases |

The matrix verifies data, views, routines, triggers, events, custom PostgreSQL schemas, MariaDB sequences, and removal
of objects that exist only in the restore target. SQLite is also exercised through restic's rclone backend.

## Prompts and safety

The safety model is:

- you must choose `local` or `production`
- destructive restores prompt for confirmation
- `restore production` requires typed confirmation, or the explicit `--confirm-production-restore` automation flag
- local restores refuse production-looking local targets

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

---

# Restore Drills

Canonical URL: https://kamal-backup.dev/restore-drills/

`drill` means "restore, check, and record the result."

Scheduled backups answer "did a backup run?" Restore drills answer the more important question: "can this Rails app actually come back from that backup?"

`kamal-backup` has two drill destinations:

- `drill local`: restore onto your machine, run an optional check, and write a drill record
- `drill production`: restore onto production infrastructure, but into scratch targets, then run an optional check and write a drill record

Every drill writes the latest result to `KAMAL_BACKUP_STATE_DIR/last_restore_drill.json`. `kamal-backup evidence` includes that latest drill record. In the accessory container, mount `/var/lib/kamal-backup` as a persistent volume if you want that record to survive accessory replacement.

## `drill local`

For a small Rails app, this is often the fastest proof that the backup is real:

```sh
bundle exec kamal-backup -d production drill local latest --check "bin/rails runner 'puts User.count'"
```

This runs on your machine, so it also requires a local `restic` install on `PATH`.

With `-d` or `-c`, `drill local` uses `config/kamal-backup.yml` for the source side:

- `app`
- the first configured database adapter
- `restic.repository`
- source paths from production `paths`

For a normal Rails app it infers part of the local target side from Rails:

- the development database in `config/database.yml`
- `tmp/kamal-backup` as the local drill state directory

File paths are never inferred. When production paths are configured, list the corresponding local targets in `config/kamal-backup.local.yml`. Database-only drills need no local file paths.

You still provide local secrets in env.

It does the same restore work as `restore local`, then runs the optional check command and stores the result. Configure any explicit local targets in `config/kamal-backup.local.yml`.

For larger apps, treat `drill local` as a convenience. The main drill should usually be `drill production`.

## `drill production`

This is the production-side drill:

- restore each database into a scratch database or scratch SQLite file
- restore configured paths into a scratch path
- run an optional verification command
- write the JSON result for evidence

It does **not** restore into the live production database.

PostgreSQL and MySQL/MariaDB scratch databases must already exist and must be dedicated to the drill. Before each
drill, `kamal-backup` resets their existing schema objects so a reused scratch target proves an exact restore rather
than accumulating objects from earlier runs. SQLite scratch restores replace the scratch database through SQLite's
restore API and verify its integrity.

PostgreSQL example:

```sh
bundle exec kamal-backup -d production drill production latest \
  --database app_restore_20260423 \
  --files /restore/files \
  --check "test -d /restore/files/data/storage"
```

MySQL/MariaDB example:

```sh
bundle exec kamal-backup -d production drill production latest \
  --database app_restore_20260423 \
  --files /restore/files \
  --check "test -d /restore/files/data/storage"
```

SQLite example:

```sh
bundle exec kamal-backup -d production drill production latest \
  --sqlite-path /restore/db/restore.sqlite3 \
  --files /restore/files \
  --check "test -f /restore/db/restore.sqlite3"
```

For PostgreSQL and MySQL, if you omit `--database` in an interactive session, `kamal-backup` asks for the scratch database name. Non-interactive runs should pass it explicitly. When multiple databases are configured, that value is used as a prefix and the database name is appended.

## Scheduling

Production drills are usually worth scheduling, but separately from ordinary backups. They have different runtime, different failure semantics, and different cleanup needs.

A typical review-friendly cadence is:

1. scheduled backups
2. regular `check`
3. a deliberate `drill production`
4. `evidence`

## What to keep for a security review

The drill JSON is the machine-readable record.

The human-readable story should usually say:

- when the drill ran
- who ran it
- which snapshot was restored
- whether it was a local or production-side drill
- which scratch targets were used
- which verification command ran
- whether the result looked correct

That is much stronger than saying "we have backups."

---

# Migrating to a new host

Canonical URL: https://kamal-backup.dev/migrating-hosts/

Moving an app to a new server is the same problem as recovering from losing one, minus the panic. If your backups are real, a migration is just a restore you chose to do. This guide walks the whole sequence, and calls out the one thing that will quietly corrupt your snapshot history if you get the order wrong.

## The trap: a fresh accessory backs up immediately

The backup accessory starts its schedule the moment it boots. On a new host that means it will snapshot an **empty database** into your repository before you have restored anything.

Nothing errors. You now have a legitimate-looking recent snapshot containing nothing, sitting at the top of `kamal-backup list`. If you later restore "the latest snapshot" during a real incident, you restore the empty one.

So the rule for the new host is: **do not let it back up until it holds the data.**

That is what `backup.enabled` is for.

```yaml
backup:
  schedule: 1d
  enabled: false
```
{: data-title="config/kamal-backup.yml on the new host"}

With `enabled: false` the accessory still boots and stays up, and `restore`, `list`, `check` and `evidence` all work through it. It simply never writes a backup. Flip it to `true` and redeploy once the restore is verified.

## Sequence

The old host keeps serving traffic throughout. Nothing is destructive until you change DNS, and even that is reversible.

### 1. Prepare the new host

Deploy the app as normal, but point it at a hostname that is not yet your production domain — `beta.example.com` works well, because it gets you a real TLS certificate and a real URL to click around in.

Boot every accessory **except** the backup one, or boot it with `enabled: false`. Do not boot a backup accessory that is both enabled and pointed at your production repository.

```yaml
backup:
  schedule: 1d
  enabled: false
```
{: data-title="config/kamal-backup.yml"}

Use `kamal setup`, not `kamal deploy`. Setup installs Docker if needed and boots the accessories as part
of the deploy; `deploy` assumes they already exist. On a new host `deploy` starts the app against a
database container that was never created, and it fails its health check with a name resolution error:

```sh
bin/kamal setup -d beta
```

It does not matter that the deploy runs `db:prepare` and creates an empty schema before you restore.
`restore production` drops and recreates the schema.

### 2. Take a fresh backup on the old host

```sh
bin/kamal accessory exec backup "kamal-backup backup --force"
bundle exec kamal-backup list
```

Confirm the snapshot you are about to restore is the one you just took.

### 3. Restore onto the new host

```sh
bundle exec kamal-backup restore production -d beta
```

`--yes` deliberately does not cover this command. For unattended runs pass `--confirm-production-restore`,
which exists to make the intent explicit rather than incidental.

Keep the local gem and the remote accessory on the same version. `kamal-backup` refuses to run when they
differ, which is usually a sign the accessory needs `bin/kamal accessory reboot backup`.

This restores the database and any configured file paths into the new host's live targets. Because the new host is not yet serving your domain, "production" here means the new machine's production database, which is exactly what you want.

The restore replaces the database, dropping and recreating the schema first, so it does not matter that the deploy already ran `db:prepare` and created an empty one.

Make sure the accessory's storage volume is **writable**. The documented default has no `:ro`; a backup-only accessory may append it, but then a file restore cannot write Active Storage contents back.

### 4. Verify before you commit to anything

Click through the beta hostname as a real user. Check row counts, uploaded files, and anything backed by Active Storage. This is the part people skip and then regret.

```sh
bundle exec kamal-backup evidence
```

Check the encrypted columns specifically. If your framework encrypts data at rest — Rails' Active Record
Encryption derives its keys from `RAILS_MASTER_KEY` — restored rows are only useful if the new host holds
the same secret. Row counts matching is not evidence of that; decrypting a value is:

```sh
bin/kamal app exec -d beta --reuse 'bin/rails runner "puts Credential.first.access_token.present?"'
```

A host with a different master key restores every byte and then fails to read any of it.

If you have OAuth or webhook integrations, remember their redirect URIs and callback URLs point at your production domain. Either register the beta hostname with those providers, or accept that you are verifying everything else now and those at cutover.

### 5. Cut over

Point DNS at the new host. Lower the TTL a day ahead so propagation is minutes rather than hours.

Two things bite immediately after the record changes, and neither looks like what it is.

**Clear the old host key.** Your hostname now resolves to a different machine, so the entry in
`~/.ssh/known_hosts` is the old server's. The next deploy builds and pushes the image, then dies at the
SSH connection with `Net::SSH::HostKeyMismatch`. Nothing in the output mentions DNS or the host move, so
it reads like a broken deploy:

```sh
ssh-keygen -R your-app.com
ssh-keyscan your-app.com >> ~/.ssh/known_hosts
```

Remove **every** key type for the name, not just the one in the error. A leftover RSA or ECDSA entry from
the old host fails the same way even once the ED25519 entry is correct.

**Deploy the default destination, not the staging one.** It is tempting to add the production hostname to
the staging destination that is already running, but the proxy rejects that with
`host settings conflict with another service`, because that service already claims the staging hostname.
Deploy the normal configuration instead. Now that DNS points at the new machine, the host entry in your
main `deploy.yml` resolves there, so a plain `kamal deploy` lands on the new server and claims the
production hostnames as a separate service:

```sh
bin/kamal deploy
```

Then remove the staging containers and its proxy route:

```sh
bin/kamal app stop -d beta
docker exec kamal-proxy kamal-proxy remove your-app-web-beta
```

If there was a window between your backup and the cutover where the old host accepted writes, take a final backup on the old host and restore again on the new one before flipping. For a quiet app this is often unnecessary; check rather than assume.

### 6. Swap which host backs up

This is the step that is easy to forget, and it matters: **two hosts must never back up to the same repository.** Divergent data in one repository makes the snapshot history ambiguous, which defeats the point of having it.

On the **new** host, enable backups:

```yaml
backup:
  schedule: 1d
  enabled: true
```
{: data-title="config/kamal-backup.yml"}

```sh
bin/kamal accessory reboot backup
bin/kamal accessory exec backup "kamal-backup backup --force"
bundle exec kamal-backup list
```

On the **old** host, disable them:

```yaml
backup:
  schedule: 1d
  enabled: false
```
{: data-title="config/kamal-backup.yml"}

```sh
bin/kamal accessory reboot backup
```

The old accessory stays up with its configuration intact, so you can still restore *from* the repository onto the old host if you need to roll back. It just stops writing to it.

If you plan to keep both hosts running for a while, give the old one its own repository path instead of disabling it, so both retain independent history.

## Rolling back

Point DNS back at the old host. It has been running the whole time and its data is only stale by whatever was written after the final backup. If you need that data, restore the newest snapshot from the new host onto the old one — the old accessory still has the configuration to do it.

## Why this is worth doing deliberately

A migration exercises the restore path with real production data and a real deadline. Most backup systems are never tested until the day they are needed, and that is a bad day to discover a problem.

Keep the `kamal-backup evidence` output from step 4. It records the snapshots restored, the check results and the tool versions, which is exactly the artifact a security review or a SOC 2 auditor asks for when they want proof that backups restore rather than merely run.

---

# Evidence for Security Reviews

Canonical URL: https://kamal-backup.dev/evidence/

`kamal-backup evidence` exists for the moment when someone asks, "Show me how this Rails app's backups are configured today, whether they run on a schedule, and whether you have tested restores."

That might be:

- a reviewer for a security program like CASA;
- a customer security questionnaire;
- your own internal ops review;
- an incident retrospective after a restore drill.

The command prints a redacted JSON summary:

```sh
bin/kamal accessory exec backup "kamal-backup evidence"
```

The JSON includes:

- app name
- current time
- configured databases
- redacted restic repository
- configured file backup paths
- whether client-side forget/prune is enabled
- retention policy
- latest database and file snapshots
- last tracked `kamal-backup check` result
- last tracked restore drill result
- image version
- installed tool versions

Secrets, passwords, access keys, and database URL credentials are redacted before output.

## How to use this for a security review

`evidence` is not the entire story by itself. It is the machine-readable appendix that backs up the story you tell in the review.

A practical workflow looks like this:

1. Run backups on a schedule.
2. Run `kamal-backup check` on a schedule, or enable `restic.check_after_backup`.
3. Run `kamal-backup drill production` against a scratch target, or `kamal-backup drill local` for a smaller app.
4. Keep a short human note when you want operator context beyond the drill JSON:
   date, operator, snapshot restored, target used, and whether the app data looked correct.
5. Run `kamal-backup evidence` and include the JSON with the review packet.

For many reviews, that combination is what matters:

- current backup configuration
- recent backup timestamps
- `kamal-backup check` results
- a real restore drill, not just successful backup logs

## Repository checks

Run checks manually:

```sh
bin/kamal accessory exec backup "kamal-backup check"
```

Or enable checks after successful backups:

```sh
restic:
  check_after_backup: true
  check_read_data_subset: 5%
```

The latest check result is stored under `KAMAL_BACKUP_STATE_DIR` and included in evidence output when available. The latest restore drill result is stored there too.

In the accessory container, the default state directory is `/var/lib/kamal-backup`. Mount that path as a persistent volume if you want the latest check and restore drill records to survive accessory replacement.

## What reviewers usually want to hear

Avoid generic phrases like "we have backups." Say something concrete instead:

- backups run from a dedicated Kamal accessory on a defined schedule
- PostgreSQL, MySQL/MariaDB, or SQLite are backed up with database-native export tools
- file-backed Active Storage files are backed up from mounted volumes
- restores are explicit, prompted operations with separate local and production-side drill flows
- the team runs restore drills and keeps evidence output

---

# Upgrading

Canonical URL: https://kamal-backup.dev/upgrading/

This page collects version-specific upgrade notes. Read the section for every version newer than the one you currently run.

## Upgrading to 0.3

0.3 changes the shape of `config/kamal-backup.yml`. The old flat YAML keys are no longer supported.

The goal is to make one Kamal deployment explicit: one app, multiple databases if needed, simple filesystem paths, restic settings, and one backup schedule.

## Config shape

Before 0.3:

```yaml
accessory: backup
app_name: chatwithwork
database_adapter: postgres
database_url: postgres://chatwithwork@chatwithwork-db:5432/chatwithwork_production
backup_paths:
  - /data/storage
restic_repository: s3:https://s3.example.com/chatwithwork-backups
restic_init_if_missing: true
backup_schedule_seconds: 86400
```
{: data-title="config/kamal-backup.yml"}

In 0.3:

```yaml
app: chatwithwork
accessory: backup

databases:
  - name: app
    adapter: postgres
    url: postgres://chatwithwork@chatwithwork-db:5432/chatwithwork_production
    password:
      secret: DATABASE_PASSWORD

paths:
  - /data/storage

restic:
  repository: s3:https://s3.example.com/chatwithwork-backups
  password:
    secret: RESTIC_PASSWORD
  init_if_missing: true

backup:
  schedule: 1d
```
{: data-title="config/kamal-backup.yml"}

## Key mapping

- `app_name` becomes `app`.
- `database_adapter` and `database_url` move under `databases`.
- `sqlite_database_path` becomes `databases[].path`.
- `backup_paths` becomes `paths`.
- `restic_repository` becomes `restic.repository`.
- `restic_init_if_missing` becomes `restic.init_if_missing`.
- `backup_schedule_seconds: 86400` becomes `backup.schedule: 1d`.
- `state_dir` becomes `state.path`.

Restic retention and check settings also move under `restic`:

```yaml
restic:
  check_after_backup: true
  check_read_data_subset: 5%
  forget_after_backup: true
  retention:
    keep_last: 7
    keep_daily: 7
    keep_weekly: 4
    keep_monthly: 6
    keep_yearly: 2
```
{: data-title="config/kamal-backup.yml"}

## Secrets

0.3 keeps secret values out of `kamal-backup.yml`. The YAML names the env var, and Kamal provides the value through `env.secret`.

For database passwords:

```yaml
databases:
  - name: app
    adapter: postgres
    url: postgres://chatwithwork@chatwithwork-db:5432/chatwithwork_production
    password:
      secret: DATABASE_PASSWORD
```
{: data-title="config/kamal-backup.yml"}

Then pass that secret in Kamal:

```yaml
accessories:
  backup:
    env:
      secret:
        - DATABASE_PASSWORD
        - RESTIC_PASSWORD
        - AWS_ACCESS_KEY_ID
        - AWS_SECRET_ACCESS_KEY
```
{: data-title="config/deploy.yml"}

If the whole database URL is secret, use:

```yaml
databases:
  - name: app
    adapter: postgres
    url:
      secret: DATABASE_URL
```
{: data-title="config/kamal-backup.yml"}

The same pattern works for restic:

```yaml
restic:
  repository:
    secret: RESTIC_REPOSITORY
  password:
    secret: RESTIC_PASSWORD
```
{: data-title="config/kamal-backup.yml"}

## Multiple databases

0.3 supports multiple databases within the same Kamal deployment:

```yaml
databases:
  - name: app
    adapter: postgres
    url: postgres://chatwithwork@chatwithwork-db:5432/chatwithwork_production
    password:
      secret: APP_DATABASE_PASSWORD

  - name: solid_queue
    adapter: postgres
    url: postgres://chatwithwork@chatwithwork-db:5432/chatwithwork_queue_production
    password:
      secret: SOLID_QUEUE_DATABASE_PASSWORD
```
{: data-title="config/kamal-backup.yml"}

This is for multiple databases or accessories inside one Kamal deployment. It is not intended for one backup accessory to cross into separate Kamal deployments.

## Local overrides

If you had `config/kamal-backup.local.yml`, migrate it to the same shape:

```yaml
databases:
  - name: app
    adapter: postgres
    url: postgres://localhost/chatwithwork_development

paths:
  - storage

state:
  path: tmp/kamal-backup
```
{: data-title="config/kamal-backup.local.yml"}

If production paths differ from local paths and you are not running through Kamal with `-d` or `-c`, set `restore_from`:

```yaml
paths:
  - storage
restore_from:
  - /data/storage
```
{: data-title="config/kamal-backup.local.yml"}

## Validate

After changing the config, run:

```sh
bundle exec kamal-backup validate
```

If validation reports a legacy key such as `database_adapter`, `backup_paths`, or `restic_repository`, that key still needs to be moved into the 0.3 shape.

---

# Commands

Canonical URL: https://kamal-backup.dev/commands/

## Main shape

The local gem is the operator-facing interface.

Use `-d` and `-c` the same way you use them with Kamal:

```sh
bundle exec kamal-backup backup
bundle exec kamal-backup evidence
bundle exec kamal-backup -c config/deploy.staging.yml -d staging check
bundle exec kamal-backup restore local latest
```

From an app checkout with the default `config/deploy.yml`, `backup`, `list`, `check`, `unlock`, `evidence`, `validate`, and `version` infer the backup accessory and shell out through Kamal. Use `-d` and `-c` when you need an explicit Kamal destination or config file. Local commands run on your machine.

The command surface is:

```sh
kamal-backup init
kamal-backup backup
kamal-backup restore local [snapshot-or-latest]
kamal-backup restore production [snapshot-or-latest]
kamal-backup drill local [snapshot-or-latest]
kamal-backup drill production [snapshot-or-latest]
kamal-backup list
kamal-backup check
kamal-backup unlock
kamal-backup prune
kamal-backup evidence
kamal-backup validate
kamal-backup schedule
kamal-backup version
```

Use `kamal-backup help` for the command list. Use command `--help` for task-specific options:

```sh
kamal-backup restore local --help
kamal-backup drill production --help
```

## Common commands

| Command | Description |
|---|---|
| `init` | Create `config/kamal-backup.yml` with the normal YAML-first shape, then print an accessory snippet to add to `config/deploy.yml`. It does not edit `config/deploy.yml` or create `config/kamal-backup.local.yml`. Create the local file to configure local file restore targets or override other Rails local defaults. |
| `backup` | Run a backup when `backup.schedule` is due, or report when the latest backup is still current. Use `--force` to create an immediate snapshot anyway. From an app checkout with `config/deploy.yml`, or with `-d`/`-c`, it runs on production infrastructure through Kamal. Remote execution requires the local gem and accessory versions to match. |
| `restore local [snapshot-or-latest]` | Restore onto your machine: current local database plus explicitly configured local file paths. Prompts before overwriting local data. With `-d` or `-c`, the source-side defaults come from `config/kamal-backup.yml`. |
| `restore production [snapshot-or-latest]` | Restore back into the live production database and production Active Storage path from `config/kamal-backup.yml`. Requires typed confirmation before overwriting production data. With `-d` or `-c`, it shells out through Kamal and requires matching local/remote versions. |
| `drill local [snapshot-or-latest]` | Restore onto your machine, optionally run `--check`, print JSON, and store the latest drill record under `KAMAL_BACKUP_STATE_DIR`. With `-d` or `-c`, the source-side defaults come from `config/kamal-backup.yml`. |
| `drill production [snapshot-or-latest]` | Restore into scratch targets on production infrastructure, optionally run `--check`, print JSON, and store the latest drill record. Use `--database` for PostgreSQL/MySQL or `--sqlite-path` for SQLite. Use `--files` for the scratch Active Storage target; the default is `/restore/files`. Remote execution requires matching local/remote versions. |
| `list` | Show restic snapshots for the configured app tags. From an app checkout with `config/deploy.yml`, or with `-d`/`-c`, it runs through Kamal against the backup accessory and requires matching local/remote versions. |
| `check` | Verify the restic repository and store the latest result under `KAMAL_BACKUP_STATE_DIR`. From an app checkout with `config/deploy.yml`, or with `-d`/`-c`, it runs through Kamal against the backup accessory and requires matching local/remote versions. |
| `unlock` | Clear stale restic repository locks. Use this when restic reports that the repository is already locked, then retry the blocked command. From an app checkout with `config/deploy.yml`, or with `-d`/`-c`, it runs through Kamal against the backup accessory and requires matching local/remote versions. |
| `prune` | Apply `restic.retention` with `restic forget --prune`, scoped separately for each configured database and file snapshot group. From an app checkout with `config/deploy.yml`, or with `-d`/`-c`, it runs through Kamal against the backup accessory and requires matching local/remote versions. |
| `evidence` | Print redacted JSON for ops records or security reviews, including latest snapshots, latest check result, latest drill result, retention, and tool versions. From an app checkout with `config/deploy.yml`, or with `-d`/`-c`, it runs through Kamal against the backup accessory and requires matching local/remote versions. |
| `validate` | Validate the backup configuration without running a backup. From an app checkout with `config/deploy.yml`, it validates the backup accessory and `config/kamal-backup.yml` before the accessory has to be running. Use `-d` or `-c` for an explicit Kamal context. |
| `schedule` | Run the foreground scheduler loop that performs backups every `backup.schedule`. Normally the accessory container runs this by default, but you can also invoke it explicitly through `-d` or `-c` when debugging. Remote execution requires matching local/remote versions. |
| `version` | Print the running `kamal-backup` version. `--version` and `-v` print the local gem version. From an app checkout with `config/deploy.yml`, `version` also prints the accessory version and sync status; `-d` and `-c` still work when you need an explicit Kamal context. |

## Notes

- `local` always means your machine, not "whatever environment the command is running in."
- `restore local` and `drill local` require `restic` on your machine.
- `production` means the production-side accessory context.
- `validate` is a preflight check. It cannot prove that server-only files exist, but it catches missing required accessory settings and required Kamal secrets that resolve to empty values before boot.
- Remote-backed commands fail fast when the local gem version and accessory version drift. The fix is `bin/kamal accessory reboot backup`.
- `drill production` restores into scratch targets on production infrastructure. It does not touch the live production database.
- Destructive restore commands prompt by default. Add `--yes` for local restores and drills in automation. `restore production` deliberately ignores `--yes`; use `--confirm-production-restore` only for deliberate production restore automation.

---

# Security and Restore Safety

Canonical URL: https://kamal-backup.dev/security/

## Secrets

`kamal-backup` redacts secrets in evidence and command failure output. It treats values from keys containing words such as `password`, `secret`, `token`, `key`, and `credential` as sensitive.

Do not put cloud credentials in clear Kamal environment. Use Kamal secrets for:

- `RESTIC_PASSWORD`;
- `AWS_ACCESS_KEY_ID`;
- `AWS_SECRET_ACCESS_KEY`;
- rclone tokens, passwords, and `RCLONE_CONFIG_PASS`;
- database passwords such as `DATABASE_PASSWORD`, `PGPASSWORD`, or `MYSQL_PWD`.

Store a copy of `RESTIC_PASSWORD` outside the app repository and outside the S3 bucket. Restic repositories are encrypted with that password; without it, the backup data is not recoverable.

For SFTP repositories, use a dedicated SSH key restricted to the backup account and repository path. Mount only that
key and a verified `known_hosts` file into the accessory; do not expose the Kamal host's entire `.ssh` directory. The
SSH credential controls access to the repository host, while `RESTIC_PASSWORD` separately encrypts the repository.

For rclone repositories, mount only the required rclone config file, read-only. Keep it outside the app repository
when it contains credentials, and supply its encryption password as the Kamal secret `RCLONE_CONFIG_PASS`.

## Subprocess execution

External tools are executed with argument arrays, not shell interpolation. The backup container does not need application source code.

## Database backups

Database backups use database-native export tools:

- PostgreSQL: `pg_dump --format=custom --no-owner --no-privileges`
- MySQL/MariaDB: `mariadb-dump` or `mysqldump` with transaction-safe defaults
- SQLite: `sqlite3 <db> ".backup ..."`

This is why the docs talk about database backups rather than raw database directories. `kamal-backup` is exporting application data with the tools Rails teams already use for dumps and restores.

Database passwords passed as `PGPASSWORD` or `MYSQL_PWD` are redacted from command summaries and failure output.

## Active Storage backups

File-backed Active Storage files are backed up from configured mounted paths with `restic backup`. A backup-only
accessory can mount the production storage volume read-only so the container cannot modify it. `restore production`
requires that mount to be writable; remove `:ro` and reboot the accessory before restoring files.

SQLite is the exception when the live database is on that storage volume. Rails SQLite apps commonly use WAL mode, and live WAL backups need normal read-write access to the database, WAL, and shared-memory files. For the normal SQLite setup, mount the storage volume read-write and point the SQLite database `path` at the live database. If the backup accessory must have no write access to app storage, back up a writer-created WAL-less snapshot instead.

## Deliberate restores

Restore commands are explicit and deliberate:

- operators must choose `restore local`, `restore production`, `drill local`, or `drill production`
- destructive restore commands prompt for confirmation unless an explicit automation flag is passed
- `restore production` asks for typed confirmation and ignores the generic `--yes` shortcut
- local restores refuse production-looking local targets
- production drills restore into scratch targets, not the live production database
- production-side commands can be run from the local gem with `-d` or `-c`, but the destructive work still happens on the backup accessory with the same explicit command surface

Those checks are there to make restores deliberate. They also help when you need to explain to a reviewer that a restore drill cannot quietly point back at production by accident.

---

# Docs Deployment

Canonical URL: https://kamal-backup.dev/deployment/

The docs live in `docs/` and use `jekyll-vitepress-theme`.

Local build:

```sh
cd docs
bundle install
bundle exec jekyll build
```

Local server:

```sh
cd docs
bundle exec jekyll serve --livereload
```

GitHub Actions builds the docs on pull requests. On pushes to the repository default branch, it uploads the built site with `actions/upload-pages-artifact` and deploys it with `actions/deploy-pages`.

No `gh-pages` branch is used.

---

# About kamal-backup

Canonical URL: https://kamal-backup.dev/about/

`kamal-backup` gives Rails teams a small, Kamal-native way to run encrypted backups on a schedule, verify restores, and produce review evidence without maintaining separate backup glue.

The project is packaged as a Ruby gem and a production accessory image. It uses restic as the backup repository format, supports PostgreSQL, MySQL/MariaDB, and SQLite database exports, and can include file-backed Active Storage paths mounted into the backup accessory.

## Start Here

- [Getting Started](/getting-started/) covers installation, the generated config, the Kamal accessory, and the first backup.
- [How Backups Work](/how-backups-work/) explains the restic snapshot model, database exports, file snapshots, checks, restore drills, and evidence.
- [Configuration](/configuration/) documents YAML settings, secrets, retention, and local restore overrides.
- [Commands](/commands/) lists the operator-facing command surface.

## Project Links

- [Source code](https://github.com/crmne/kamal-backup)
- [RubyGems package](https://rubygems.org/gems/kamal-backup)
- [Container package](https://github.com/crmne/kamal-backup/pkgs/container/kamal-backup)