Backup & Maintenance

PicFast includes a Maintenance Dashboard in the admin console to view disk health, database statistics, and pHash coverage, along with a built-in cleanup tool. For deeper operations, the picfast maintenance CLI handles consistency checks, backups, restores, and thumbnail repairs.

Admin Dashboard

Navigate to Maintenance in the admin console to monitor system health and perform routine cleanups:

Disk Health: Real-time storage capacity, usage, and inode statistics for the local backend.
Database Stats: Overview of row counts, sizes, and pHash calculation coverage.
Cleanup Tool: Identify and delete unlinked objects from the storage backend (files without a database record).
Risk Audit: Check for configurations that might pose a security or operational risk.

CLI: 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`).
`recalc-phash`	Recalculates missing perceptual hashes (pHash) for all eligible images.

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.