Skip to content

Backup & Restore

Jump to bottom
Dennis edited this page Jun 20, 2026 · 5 revisions

Backup and Restore

This page covers the supported backup and restore operations for Docker Compose installs. For installation, reverse proxy, phone sync, and production setup, use the Self-Hosting Guide.

Supported paths

Need Supported path
Routine app backup Admin panel backup schedule or manual export
Fresh-instance restore Setup wizard restore from a Tribu backup archive
Operator-level PostgreSQL backup Docker Compose commands on this page
Operator-level PostgreSQL restore drill Docker Compose commands on this page, preferably on a fresh test stack

Legacy repository-local helper scripts are no longer part of the supported operator surface. Use the Admin panel, setup wizard, or the Compose commands below so the runbook stays visible and reviewable.

Prerequisites

  • Docker with Compose v2 is installed and running.
  • Tribu uses the standard Compose setup or an equivalent stack.
  • The backend can write to /backups when using the built-in Admin backup flow.
  • You know where your .env, Compose file, reverse proxy config, and TLS material are stored.
  • You can run docker compose in the directory that contains your Tribu Compose file.

What is included

Included in Tribu backup Not included
PostgreSQL database dump .env secrets
backup metadata reverse proxy config
family data stored in the database TLS certificates
calendars, contacts, birthdays, tasks, shopping, rewards, gifts, recipes, meal plans, settings host-level files outside the database and backup volume
OIDC settings stored in the database external storage configuration

Valkey is not backed up because it stores cache data only.

Admin panel backup

Admins can manage backups from the Admin panel.

Schedule

Open Admin > Backups and choose a schedule:

Preset When
Off No automatic backups
Daily Every day at 03:00
Weekly Every Sunday at 03:00
Monthly 1st of each month at 03:00

Set retention to control how many backups are kept. Older backups are deleted automatically.

Manual backup

Click Create backup to trigger a backup immediately. The archive appears in the list and can be downloaded.

The archive is named like tribu-backup-YYYY-MM-DD-HHMMSS.tar.gz and contains:

  • database.dump: PostgreSQL dump in custom format
  • metadata.json: backup version, Alembic revision, PostgreSQL version, timestamp

External storage for app backups

By default backups are stored in a Docker volume. For a NAS or external drive, bind mount a host path to /backups on the backend service:

backend:
  volumes:
    - /mnt/nas/backups/tribu:/backups

Make sure the backend container can write to that path.

Compose backup commands

Use this when you want a plain PostgreSQL dump from the Compose stack. Run the commands in the directory that contains docker-compose.yml.

Create a timestamped backup directory:

mkdir -p backups
BACKUP_FILE="backups/tribu-db-$(date +%Y-%m-%d-%H%M%S).dump"

Create the dump:

docker compose exec -T postgres \
  pg_dump -U tribu -d tribu -Fc \
  > "$BACKUP_FILE"

Optionally record the current migration revision next to the dump:

docker compose exec -T postgres \
  psql -U tribu -d tribu -t -A \
  -c "SELECT version_num FROM alembic_version LIMIT 1" \
  > "${BACKUP_FILE%.dump}.alembic.txt"

Check that the file exists and is non-empty:

ls -lh "$BACKUP_FILE"

Store the dump somewhere other than the same disk when possible. Treat the dump as sensitive household data.

Restore through the setup wizard

Use this for normal Tribu backup archives created by the Admin panel.

  1. Start a fresh Tribu stack with a new database volume.
  2. Configure .env manually. Secrets are not included in the backup.
  3. Set SETUP_RESTORE_TOKEN in .env if you want to protect restore upload during first setup.
  4. Open the setup wizard and choose Restore from backup.
  5. Upload the tribu-backup-*.tar.gz archive.
  6. Sign in and verify the household data and integrations.

Compose restore commands

Use this for a PostgreSQL dump created with the Compose backup commands above. Test this on a fresh stack before relying on it for an outage.

Set the backup file you want to restore:

BACKUP_FILE="backups/tribu-db-2026-02-24-143022.dump"

Stop app traffic and keep PostgreSQL running:

docker compose stop backend frontend
docker compose up -d postgres

Drop and recreate the application database:

docker compose exec -T postgres \
  psql -U tribu -d postgres \
  -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = 'tribu' AND pid <> pg_backend_pid();"

docker compose exec -T postgres dropdb -U tribu --if-exists tribu
docker compose exec -T postgres createdb -U tribu -O tribu tribu

Restore the dump:

docker compose exec -T postgres \
  pg_restore -U tribu -d tribu --no-owner --no-privileges \
  < "$BACKUP_FILE"

Start Tribu again. The backend runs pending migrations on startup:

docker compose up -d

Restore drill checklist

Do not wait for a real outage to test restore.

  1. Start a fresh Tribu stack with a new database volume.
  2. Restore a recent backup.
  3. Sign in and verify:
    • family exists
    • calendar, tasks, shopping, contacts, rewards, gifts, recipes, meal plans, and settings are present
    • migrations completed
    • reverse proxy and phone sync still use the expected public URL
  4. Confirm .env, Compose overrides, reverse proxy config, TLS certificates, and external mount configuration are covered by your normal server backup.

Important notes

  • Changing JWT_SECRET invalidates existing sessions and tokens.
  • OIDC client secrets stored in the database are part of the database backup. Treat backup archives and dumps as sensitive.
  • Keep .env, Compose overrides, reverse proxy config, TLS certificates, and external mount configuration in your normal server backup.
  • Store backups somewhere other than the same disk when possible.
  • Test restore after major upgrades.

Troubleshooting

Backup creation fails

  • Check docker compose logs backend for Admin panel backups.
  • Check docker compose logs postgres for Compose-level dumps.
  • Confirm the backend can write to /backups when using Admin panel backups.
  • Check free disk space.
  • If using a NAS mount, check mount permissions and availability.

Restore fails

  • Confirm the archive or dump comes from the expected Tribu instance.
  • Use a fresh database volume for restore drills.
  • Confirm the target version can run pending migrations.
  • For Admin panel backup archives, restore through the setup wizard.
  • For raw PostgreSQL dumps, use the Compose restore commands on this page.

Restored instance cannot log in

  • Confirm JWT_SECRET is set.
  • If you changed JWT_SECRET, existing sessions and tokens are invalid and users need to log in again.
  • Check OIDC settings if SSO is enabled.

Related pages

Clone this wiki locally