Archigov · docs
  1. Docs
  2. Guides

Backups and Upgrades

Nightly backups, pre-migration snapshots, continuous Litestream replication to S3, R2 or MinIO, restoring, and upgrading safely.

#What Is Protected Automatically

MechanismWhenWhereKept
Nightly backupEvery night/data/backups/backup-<timestamp>.dbThe last 14
Pre-migration snapshotBefore any schema migration runs on an existing database/data/backups/pre-migration-v<N>-<time>.dbUntil you remove them
On demandSettings → General → Data & Backups (platform admin), or POST /api/backup/data/backups/With the nightly set

Backups are consistent SQLite online backups; the instance keeps running. Settings shows the time of the last backup.

Warning

Backups live on the same volume as the database. Copy them off the host, or use Litestream, so that losing the volume does not lose the backups.

#The Keys Directory

/data/keys holds the evidence-signing key pair, the session secret, and — if ARCHIGOV_SECRET_KEY is not set — the secret key that encrypts stored AI provider keys. It is never included in backups or Litestream replicas, by design. Back it up separately, to a secret store:

  • Losing the signing key means new evidence packs are signed by a new identity; old packs still verify against the old public key, which you should have recorded.
  • Losing the secret key means stored AI keys must be re-entered.
  • Losing the session secret signs everyone out.

#Continuous Replication with Litestream

The image includes Litestream (v0.5, checksum-verified at build time). It streams every change to S3-compatible storage and, on a container whose volume is empty, restores from the replica before the application starts.

Command-line mode — one URL:

Env
LITESTREAM_URL=s3://archigov-backups/prod/app.db
LITESTREAM_ACCESS_KEY_ID=<key id>
LITESTREAM_SECRET_ACCESS_KEY=<secret>
AWS_ENDPOINT=https://<account>.r2.cloudflarestorage.com   # Cloudflare R2; MinIO: http://minio:9000
AWS_REGION=auto                                            # MinIO: us-east-1

Config-file mode — mount a Litestream 0.5 YAML at /etc/litestream.yml (picked up automatically) or set LITESTREAM_CONFIG to its path. The repository's infra/litestream/ holds examples for R2 and MinIO.

Test a restore at least once: start a second container with an empty volume and the same replica settings, and check that it comes up with your data.

#Restoring from a Backup File

Shell
docker compose -f docker-compose.prod.yml stop archigov
# copy the chosen backup over the database, removing the WAL files
docker run --rm -v archigov_archigov-data:/data alpine sh -c \
  'cp /data/backups/backup-2026-10-14T02-00-00-000Z.db /data/app.db && rm -f /data/app.db-wal /data/app.db-shm'
docker compose -f docker-compose.prod.yml start archigov

The volume name depends on your compose project; check it with docker volume ls. After a restore, run GET /api/audit/verify — the chain must verify end to end.

#Upgrading

  1. Read the changelog for the target version.
  2. Take an on-demand backup and copy it off the host.
  3. Rebuild or pull the new image, and restart:
Shell
git pull && docker compose -f docker-compose.prod.yml up -d --build

On boot, pending migrations run in order, each after a pre-migration snapshot. Check /api/health and the version shown under Settings.

#Versions and Migrations

Archigov follows semantic versioning. Migrations are forward-only: a release that needs a breaking schema change is a major version. To roll back, restore the pre-migration snapshot together with the previous image — never run an older image against a migrated database.