Backups
The app creates PostgreSQL archives with pg_dump and stores them locally first; an optional
S3-compatible destination (AWS S3, Cloudflare R2, MinIO, B2 S3) receives the same archive, which
contains the database dump, so the remote copy is a full database backup.
Prerequisites
pg_dumpmust be installed on the host and match (or exceed) the server major version.pg_dumpfrom a newer major version can dump an older server; an olderpg_dumpcannot dump a newer server. PointBACKUP_PG_DUMP_PATHat the binary when it is not onPATH.- The
BACKUP_DIRdirectory is created with0700; the process user must be able to write it. - Remote storage is optional. To use a remote destination, configure the shared S3 settings.
Configuration
BACKUP_ENABLED=true # schedules + dashboard creationBACKUP_DIR=backups # relative to APP_STORAGE_DIRBACKUP_DESTINATIONS=local,s3 # local is always includedBACKUP_S3_PREFIX=backups # object key: backups/<env>/<filename>BACKUP_PG_DUMP_PATH=pg_dumpBACKUP_TIMEOUT=1hBACKUP_RUN_CRON=30 1 * * *BACKUP_CLEAN_CRON=30 2 * * *Retention follows the Laravel-backup DefaultStrategy: keep every archive for 7 days, then one per
day for 16 days, one per week for 8 weeks, one per month for 4 months and one per year for 2 years.
The newest archive is never deleted. BACKUP_MAX_TOTAL_MB (0 = unlimited) caps total storage.
BACKUP_INCLUDE_FILES=true adds the configured BACKUP_FILES_PATHS under files/ in the archive
(database-only by default). node_modules, .git, tmp and the backup directory itself are
skipped.
S3 / R2 / MinIO
The backup destination reuses the storage S3 client:
S3_ENDPOINT=https://<account>.r2.cloudflarestorage.com # omit for AWS S3S3_REGION=auto # R2 uses "auto"S3_BUCKET=my-backupsS3_ACCESS_KEY=...S3_SECRET_KEY=...S3_PATH_STYLE=true # MinIO and most S3-compatible storesBACKUP_DESTINATIONS=local,s3Each destination is attempted independently. If local succeeds and the remote copy fails, the run
is marked partial and the remote error is stored in the run’s destinations JSON.
Commands
go run ./cmd/app backup:run # synchronous manual backupgo run ./cmd/app backup:run --with-filesgo run ./cmd/app backup:run --destinations=local,s3 --filename=before-upgrade.tar.gzgo run ./cmd/app backup:list --limit=20go run ./cmd/app backup:clean --dry-rungo run ./cmd/app backup:cleango run ./cmd/app backup:monitor # exits 1 when stale/failedThe CLI works even when BACKUP_ENABLED=false; scheduling and the dashboard creation button are
gated by the flag.
Runtime
backup.runandbackup.cleanare scheduler tasks when backups are enabled.- The dashboard/API enqueues
backup.runon theheavyqueue; a Postgres advisory lock prevents overlapping runs. WithQUEUE_DRIVER=syncthe run executes inline. - The
Backupshealth check warns when the newest successful run is older thanBACKUP_MAX_AGE_HOURSor storage exceedsBACKUP_MAX_TOTAL_MB, and fails when no successful run exists. - Every run, delete and cleanup is audited in
dev_actionsand visible at/dev/backups.
Restore (manual, out of scope in v1)
The archive is a normal gzip tarball with manifest.json, database.dump (PostgreSQL custom
format) and optional files/. Restore the dump manually:
tar -xzf <archive>.tar.gz database.dumppg_restore --clean --if-exists --no-owner --no-privileges -d <database> database.dumpRestore automation, point-in-time recovery/WAL archiving, archive encryption and failure notifications are not implemented in v1.