Skip to content

Backup and restore ​

This page explains how to back up the database and attachments daily with the bundled scripts/backup.sh, and how to restore with scripts/restore.sh.

What to back up ​

ContentLocationBacked up by the script
PostgreSQL databaseGONGGONG_DATABASE_URLYes, pg_dump custom format
Attachments$GONGGONG_DATA_DIR/attachments/Yes, as a tar.gz
Data encryption keyGONGGONG_DATA_KEYNo; keep it safe separately
Managed artifacts (files of prototypes, canvases, etc.)$GONGGONG_DATA_DIR/artifacts/No; back up yourself if needed
Uploaded avatars$GONGGONG_DATA_DIR/avatars/No; back up yourself if needed
Force-synced file contents$GONGGONG_DATA_DIR/sync/No; back up yourself if needed
Base-branch mirrors$GONGGONG_DATA_DIR/mirrors/No; re-fetched from the repository if lost
Client installers$GONGGONG_DATA_DIR/downloads/No; can be uploaded again

Other contents of the data directory

backup.sh only archives attachments/. If your team uses artifacts or force sync, we recommend adding artifacts/, avatars/, and sync/ to your own file backups too (for example, a periodic rsync to a backup disk). They are also encrypted with GONGGONG_DATA_KEY.

Keep the key and the backups apart

Attachments, diffs, and run details are encrypted with GONGGONG_DATA_KEY. Without the key, that part of the backup can't be decrypted; but if the key sits next to the backups, anyone who gets the backups can decrypt everything. Keep the key separately in a secrets manager or on offline media.

Daily backups ​

Environment variables read by the script:

VariableDescription
GONGGONG_BACKUP_DIRBackup output directory (required)
GONGGONG_DATABASE_URLDatabase connection string; if unset, built from GONGGONG_DB / GONGGONG_PG_PORT, same as the server
GONGGONG_DATA_DIRServer data directory, default .gonggong-dev/data

You need to be able to run pg_dump (the same major version as the server's PostgreSQL, or newer).

Run it once by hand:

bash
cd /srv/gonggong
sudo -u gonggong env \
  GONGGONG_BACKUP_DIR=/var/backups/gonggong \
  GONGGONG_DATA_DIR=/var/lib/gonggong \
  GONGGONG_DATABASE_URL='postgres://gonggong:<密码>@127.0.0.1:5432/gonggong' \
  bash scripts/backup.sh

(<密码> = the database password.) Each run produces a pair of files named by timestamp:

text
gonggong-20260923-033000.dump
attachments-20260923-033000.tar.gz

The script keeps the latest 7 backups, plus the latest backup of each of the last 7 dates that have backups (set GONGGONG_BACKUP_KEEP to change the 7, e.g. lower it when disk is tight), and deletes the rest automatically. So a backup taken before a release isn't pushed out by later backups the same day. An attachment archive is kept or deleted together with the database backup of the same timestamp, and files whose names weren't generated by the script are left alone (the script doesn't read the system parameter 「服务器备份(每日)保留」 (Keep daily server backups for)). Files are first written as .part temporaries and renamed when complete, so a failure midway never leaves a half-written backup that looks complete.

Run it daily at 3:30 a.m. with cron:

cron
30 3 * * * GONGGONG_BACKUP_DIR=/var/backups/gonggong GONGGONG_DATA_DIR=/var/lib/gonggong GONGGONG_DATABASE_URL=postgres://gonggong:<密码>@127.0.0.1:5432/gonggong /srv/gonggong/scripts/backup.sh >> /var/log/gonggong-backup.log 2>&1

TIP

Ideally put the backup directory on a separate disk and sync it off-site regularly. Also check the backup directory's access permissions: message bodies, run cards, and so on are in plaintext in the backups.

With a Docker Compose deployment

backup.sh needs direct access to the database and the data directory, but in a compose deployment the database port isn't published and the data lives in Docker volumes. You can export the database with docker compose exec -T db pg_dump -U gonggong --format=custom gonggong > gonggong-<时间戳>.dump (<时间戳> = timestamp) and back up the data volume; the data.key in the data volume is the encryption key and must likewise be kept apart from the backups.

Restore ​

restore.sh restores the backup with a given timestamp into the currently configured database and data directory, using the same environment variables as the backup.

  1. Stop the server:
    bash
    sudo systemctl stop gonggong
  2. Make sure the target database exists (on a new machine, first create an empty database as in Deploy from source).
  3. List the available backups and restore:
    bash
    ls /var/backups/gonggong
    sudo -u gonggong env \
      GONGGONG_BACKUP_DIR=/var/backups/gonggong \
      GONGGONG_DATA_DIR=/var/lib/gonggong \
      GONGGONG_DATABASE_URL='postgres://gonggong:<密码>@127.0.0.1:5432/gonggong' \
      bash scripts/restore.sh 20260923-033000
  4. Make sure the server uses the GONGGONG_DATA_KEY from the time of the backup, then start it:
    bash
    sudo systemctl start gonggong

What the restore does:

  • The database is restored with pg_restore --clean --if-exists in a single transaction; objects with the same names in the target database are replaced, and any error rolls back the whole thing.
  • The attachments directory is deleted entirely first, then extracted from the backup.
  • If there's no attachment backup for that timestamp (no attachments existed yet), only the database is restored.

WARNING

Restoring overwrites the current data; messages, runs, and attachments after the backup point are lost. Daemon bindings on members' machines are stored in the database, so after restoring an older backup, machines bound after that point need to be bound again.

Released under the Apache License 2.0