# Backups, restoration and upgrades

Preserve persistent data and configuration, then migrate matched runtime versions with a tested recovery path.

## What to preserve

Back up PostgreSQL, object storage, shared upload data and private configuration
as one recoverable installation. Record image digests, configuration/schema
revision and the inference model versions used. Keep `AUTH_SECRET`, storage
credentials and any configured encryption keyring with restricted access.
Model/compile caches can generally be downloaded/rebuilt, but a private checkpoint
may need an independent backup and access policy.

The reference volumes are isolated under the Compose project. `down` retains
them; `down --volumes` deletes them. Never use a volume-removal command as an
ordinary update step. Backups are useful only after a restoration test.

## Example database backup

From the reference root, use the same Compose files/profile as the installation.
Pause writes and background jobs for a consistent database/storage/upload snapshot,
or use a coordinated backup mechanism appropriate to your storage system.

```sh
docker compose --env-file secrets.env stop server jobs
umask 077
docker compose --env-file secrets.env exec -T postgres pg_dump -U dicto -d dicto -Fc > dicto.dump
test -s dicto.dump
```

While writes remain paused, take the matching object-storage/upload backups and
save private config securely. Restart API/jobs with your selected prefix after
the coordinated backup completes. The dump alone does not contain recording
bytes or upload drafts. Do not publish backups or private env files in the docs.

## Upgrade sequence

1. Review release notes and compatibility; pin the same new server image for
   migrator/API/jobs, and review the management/client versions.
2. Validate the new configuration with that image before changing live services.
3. Verify a recoverable coordinated backup and retain old image references.
4. Stop API/jobs before applying an incompatible schema migration.
5. Run the new migrator and require a zero exit code.
6. Start matched API/jobs and browser applications; verify sign-in, playback,
   transcription and each configured AI feature.

For the reference core, after updating the reviewed image reference:

```sh
docker compose --env-file secrets.env pull migrator server jobs management
docker compose --env-file secrets.env stop server jobs
docker compose --env-file secrets.env run --rm --no-deps migrator migrate
docker compose --env-file secrets.env up -d server jobs management
```

Keep all selected overlay files/profile flags when managing a self-hosted AI or
monitoring installation. An old image does not reverse database migrations.
Recovery after an incompatible migration may require restoring database,
storage/uploads, config and compatible images together into an isolated host.
Perform and record that restore exercise before relying on the procedure.