Skip to content

Backup & Restore

Jump to bottom
itsDNNS edited this page Apr 30, 2026 · 5 revisions

Backup and Restore

This page covers backup-specific operations. For installation, reverse proxy, phone sync, and production setup, use the Self-Hosting Guide.

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
  • You know where your .env, Compose file, reverse proxy config, and TLS material are stored

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.

Creating a backup with the CLI

Run from the repository root:

./scripts/backup.sh

To write the archive to a specific directory, for example a NAS mount:

./scripts/backup.sh --output-dir /mnt/nas/backups/tribu

This creates a tribu-backup-YYYY-MM-DD-HHMMSS.tar.gz archive containing:

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

Backup via UI

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.

External storage

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.

Restore drill

Do not wait for a real outage to test restore.

  1. Start a fresh Tribu stack with a new database volume.
  2. Copy a backup archive to the server.
  3. Configure .env manually. Secrets are not included in the backup.
  4. Restore during the setup wizard or with the restore script.
  5. Sign in and verify:
    • family exists
    • calendar, tasks, shopping, contacts, rewards, gifts, recipes, and settings are present
    • migrations completed
    • reverse proxy and phone sync still use the expected public URL

Restoring with the CLI

./scripts/restore.sh path/to/tribu-backup-2026-02-24-143022.tar.gz

The script shows backup metadata and asks for confirmation before proceeding.

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 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.
  • Confirm the backend can write to /backups.
  • Check free disk space.
  • If using a NAS mount, check mount permissions and availability.

Restore fails

  • Confirm the archive is a Tribu backup archive.
  • Check metadata in the archive if available.
  • Use a fresh database volume for restore drills.
  • Confirm the target version can run pending migrations.

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