Servers and the panel

Panel backups

A single panel can dump its own database once a day to an S3-compatible bucket, so losing its server doesn't lose the panel (Settings → System → Panel backups).

The installer already keeps a week of local dumps in /var/backups/stackd, but on the same server as the database: losing the server loses them too. Off-site backups put a copy somewhere else.

A highly available panel doesn't need this: its database, stackd-panel, is a managed PostgreSQL database, backed up from Databases like any other. The section says so there, and the API refuses to set it up (409).

Setting it up

In the section, or with PUT /api/system/backup (admins), pick a destination: an existing one (target_id, from GET /api/backup-targets) or a new one described in full (endpoint, region, bucket, prefix, keys), checked by writing and deleting a test object, as for databases. keep (1 to 365, default 14) is how many dumps stay in the bucket.

Dumps go to <prefix>/stackd-panel/panel-<UTC time>.dump, once a day; older ones past keep are deleted. POST /api/system/backup/run takes one now. A failure is retried after half an hour, shown in the section, and sent as a Backup failed alert.

DELETE /api/system/backup stops them; the dumps stay, and so does the destination (with its keys) while any recorded backup is in it.

What's in a dump

Everything the panel stores. Secrets in it (variables, database passwords, bucket keys) are sealed with STACKD_MASTER_KEY, so the dump is only half of a restore: keep /etc/stackd/stackd.env somewhere safe as well. Anyone holding both holds every secret; keep the bucket private.

Restoring

On a new server, with the panel installed and the same STACKD_MASTER_KEY in /etc/stackd/stackd.env:

systemctl stop stackd
aws s3 cp s3://<bucket>/<prefix>/stackd-panel/panel-<time>.dump panel.dump   # or s5cmd, rclone…
. /etc/stackd/stackd.env
docker run --rm -i --network host -e DATABASE_URL postgres:18-alpine \
  sh -c 'pg_restore --clean --if-exists --no-owner --dbname="$DATABASE_URL"' < panel.dump
systemctl start stackd

Then point the panel's domain at the new server. Agents reconnect to it by themselves.