Skip to content

Backup & Restore

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

Backup and Restore

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

Prerequisites

  • Docker with Compose v2 is installed and running
  • Tribu is checked out locally so you can run the repo-local scripts from the project root
  • Your running stack follows the standard compose setup from the README or self-hosting guide

Creating a Backup

Run from the repository root:

./scripts/backup.sh

To write the archive to a specific directory (e.g. a mounted NAS share):

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

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

  • database.dump -- full PostgreSQL dump (custom format)
  • metadata.json -- backup version, Alembic revision, PG version, timestamp

Example output:

Creating Tribu backup...
  Dumping database...
  Packing archive...

Backup complete!
  Archive: tribu-backup-2026-02-24-143022.tar.gz
  Size:    1.2M
  Alembic: 0005
  PG:      16.2

Restoring on a Fresh Server

  1. Clone the repository and configure your environment:

    git clone https://github.com/itsDNNS/tribu.git
cd tribu
cp docker/.env.example docker/.env
# Edit docker/.env and set POSTGRES_PASSWORD and JWT_SECRET

  2. Copy the backup archive to the server.

  3. Run the restore script:

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

  4. The script will show backup metadata and ask for confirmation before proceeding.

Important Notes

  • Secrets are NOT included in backups. You must configure .env manually on the target server (POSTGRES_PASSWORD, JWT_SECRET).
  • Changing JWT_SECRET invalidates all existing sessions and tokens. Users will need to log in again.
  • Valkey is not backed up because it only holds ephemeral cache data.
  • The backup uses PostgreSQL's custom dump format (pg_dump -Fc), which supports selective and parallel restore.

Backup via UI

Admins can manage backups directly from the Admin panel in the web interface.

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 03:00

Set the retention count to control how many backups are kept (oldest are deleted automatically).

Manual Backup

Click Create backup to trigger an immediate backup. The archive appears in the list and can be downloaded directly from the browser.

External Storage

By default backups are stored in a Docker volume (tribu_backups). To store backups on a NAS or external drive, replace the volume mount in docker/docker-compose.yml:

volumes:
  # - tribu_backups:/backups
  - /mnt/nas/backups/tribu:/backups

The CLI scripts (scripts/backup.sh, scripts/restore.sh) continue to work independently of the UI.

Clone this wiki locally