Backup & Maintenance

PicFast includes a picfast maintenance CLI for consistency checks, backups, archive verification, restores, and optional thumbnail repair. Run commands on the server or inside the application container — not from the browser. The admin console only surfaces copy‑paste hints.

Before you run

Use the same configuration as the running instance (config.yaml / environment) so the CLI can reach PostgreSQL and your storage backends.
In Docker Compose examples below, replace <service> with your actual Compose service name for PicFast (many examples use app; yours may differ — check docker-compose.yml).
Large deployments: prefer a maintenance window — doctor and full backups can read many objects.

Command shape

docker compose exec <service> picfast maintenance <subcommand> [flags]

Use picfast maintenance --help and picfast maintenance <subcommand> --help for flags (--json, --all, --pg-dump-container, etc.).

Subcommands

Subcommand	Role
`doctor`	Read‑only check of DB rows, stored objects, and thumbnails.
`backup`	Writes a PostgreSQL custom‑format dump and can package object payloads into an archive.
`inspect`	Validates `manifest.json` and checksums inside a backup tarball.
`restore`	Preflight by default; `--apply` performs writes. Restoring into a non‑empty database requires `--force`.
`repair-thumbnails`	Rebuilds missing thumbnails from source objects (dry‑run unless `--apply`).

Typical order

Check: picfast maintenance doctor --all --batch-size 500
Backup: picfast maintenance backup --output /app/data/backups/picfast-backup.tar.gz (adjust path to match your volume mounts)
Verify archive: picfast maintenance inspect /app/data/backups/picfast-backup.tar.gz
Restore (on the target host, after checks): picfast maintenance restore … --apply — add --force only when you intend to overwrite a non‑empty database.

PostgreSQL client tools

If the host does not have pg_dump / pg_restore, the CLI can shell into a Postgres container (e.g. --pg-dump-container / --pg-restore-container) — see --help on backup and restore.

Full archive specification

Manifest schema, objects.jsonl vs checksum ledger, compatibility rules, and safety notes for operators and contributors live in the PicFast repo: docs/maintenance.md.