Backup & Restore
Back up and restore your Penombre instance.
Penombre ships with scripts to back up and restore both the PostgreSQL database and the file storage volume. Both scripts operate on a running Docker Compose deployment.
Backup
The backup script creates a single compressed archive containing the database dump, all uploaded files, and a metadata file.
./scripts/backup.sh [directory]The optional directory argument controls where the archive is saved (default: ./backups).
What's included
penombre_backup_20260318_143000.tar.gz
├── database.dump # PostgreSQL custom-format dump (gzip level 9)
├── storage.tar.gz # Contents of /data (all uploaded files)
└── backup.json # Metadata (timestamp, file sizes, version)How it works
Locates the running db and app containers via docker compose ps.
Runs pg_dump inside the database container to produce a compressed
custom-format dump.
Creates a tar archive of the /data directory from the app container.
Writes a backup.json metadata file with timestamps and file sizes.
Packages everything into a single .tar.gz archive and reports its
size.
Environment variables
| Variable | Description | Default |
|---|---|---|
POSTGRES_USER | PostgreSQL user for pg_dump | postgres |
POSTGRES_DB | Database name to dump | penombre |
COMPOSE_PROJECT_NAME | Docker Compose project name | Auto |
Scheduling backups
Use cron to run backups automatically. For example, daily at 3 AM:
0 3 * * * cd /path/to/penombre && ./scripts/backup.sh /mnt/backupsRestore
Restoring is destructive — it drops the existing database and replaces all files in storage. Always verify you have the correct backup before proceeding.
./scripts/restore.sh path/to/penombre_backup_20260318_143000.tar.gzThe script prompts for confirmation before making any changes. You must type yes to proceed.
How it works
Extracts the archive and verifies that database.dump,
storage.tar.gz, and backup.json are present.
Stops the app container to prevent writes during restore.
Drops the existing PostgreSQL database and restores from
database.dump using pg_restore.
Starts the app container, clears the current /data directory, and
extracts storage.tar.gz into it.
Restarts the app service to pick up the restored data.
Environment variables
| Variable | Description | Default |
|---|---|---|
POSTGRES_USER | PostgreSQL user for pg_restore | postgres |
POSTGRES_DB | Database name to restore into | penombre |
COMPOSE_PROJECT_NAME | Docker Compose project name | Auto |
Tips
- Test restores regularly. A backup is only useful if you can restore from it. Spin up a separate Compose stack and verify the archive works.
- Store backups off-site. Copy archives to a remote location (S3, another server, etc.) in case the host fails.
- Back up before upgrading. Always run
./scripts/backup.shbefore pulling a new Penombre image.
Found an issue or want to contribute? Edit this page on GitHub