Skip to content

Backups and upgrades

Everything lives in BUNKER_DATA_DIR: /var/lib/bunker (Linux installer), /data (containers), else ./bunker-data.

Path
bunker.db, bunker.db-wal, bunker.db-shm The SQLite database (WAL mode): people, apps, versions, sharing, app data, settings, audit
blobs/ App files and uploads, stored by SHA-256, with .br and .gz copies
secret.key The key that encrypts secrets and signs content tickets. Back it up with the rest, or set BUNKER_SECRET_KEY yourself
certs/ Let’s Encrypt certificates, when BUNKER_TLS=auto
setup-code.txt Only until setup is done

Bunker makes a consistent backup while it runs: a SQLite snapshot (VACUUM INTO) plus the files and the key, in one .tar.gz. Blobs never change once written, so copying them live is safe. .br and .gz copies are left out; Bunker rebuilds them when needed.

Terminal window
curl -X POST -H "Authorization: Bearer $TOKEN" -OJ \
https://bunker.example.com/api/v1/admin/backup
# saves bunker-backup-20261105-021500.tar.gz

Or bunker api admin.backup > bunker-backup.tar.gz. The archive includes secret.key so encrypted settings (sign-in secret, AI keys, connection headers) restore too. Keep it as safe as the server. Add ?includeKey=false to leave the key out, if you keep it elsewhere or set BUNKER_SECRET_KEY.

Set a folder and Bunker writes a snapshot there on a schedule, and deletes old ones:

Variable Default
BUNKER_BACKUP_DIR off Folder for snapshots. A relative path is inside the data folder (backups → /var/lib/bunker/backups)
BUNKER_BACKUP_EVERY 24h How often, as a Go duration (6h, 12h, 168h). At least 1h
BUNKER_BACKUP_KEEP 7 How many snapshots to keep
/etc/bunker/bunker.env
BUNKER_BACKUP_DIR=/mnt/backups/bunker
BUNKER_BACKUP_EVERY=12h
BUNKER_BACKUP_KEEP=14
  • Files are named bunker-YYYYMMDD-HHMMSS.tar.gz (UTC) and always include secret.key.
  • The first check runs a minute after start. If the newest snapshot is older than BUNKER_BACKUP_EVERY, a new one is written.
  • A failed snapshot is logged and audited as admin.backup.failed, and retried after 15 minutes.
  • Put the folder on another disk or a mounted share. A snapshot on the same disk won’t save you from losing that disk.

See the snapshots and settings, or write one now:

Terminal window
bunker api admin.backups.list # {"enabled": true, "dir": "...", "every": "12h0m0s", "keep": 14, "backups": [...]}
bunker api admin.backups.run # writes one now

Without Bunker’s help, take a consistent database copy plus the files:

Terminal window
sqlite3 /var/lib/bunker/bunker.db "VACUUM INTO '/backup/bunker.db'"
rsync -a /var/lib/bunker/blobs /var/lib/bunker/secret.key /backup/

Or stop Bunker briefly and copy the whole folder. Disk snapshots (Azure managed disk, EBS, a Fly volume snapshot) also work: SQLite in WAL mode recovers cleanly from a crash-consistent snapshot.

bunker backup [file] downloads a consistent archive (database VACUUM INTO snapshot, blobs and secret.key) from the server you’re signed in to. It needs an admin token with the admin scope. Add --no-key to leave secret.key out.

Terminal window
bunker backup /backup/bunker-$(date +%F).tar.gz

Stop Bunker, then on the server run bunker restore <file>. It unpacks the archive into BUNKER_DATA_DIR, refuses while a server still answers on BUNKER_LISTEN, asks before replacing existing data (--yes skips the question) and keeps the old database as bunker.db.pre-restore-<time>. Start Bunker again afterwards; migrations run automatically.

Terminal window
sudo systemctl stop bunker
sudo -u bunker BUNKER_DATA_DIR=/var/lib/bunker bunker restore /backup/bunker-2026-11-05.tar.gz
sudo systemctl start bunker
  1. Stop Bunker.

  2. Unpack the backup into an empty data folder:

    Terminal window
    sudo mkdir -p /var/lib/bunker && cd /var/lib/bunker
    sudo tar -xzf /mnt/backups/bunker/bunker-20261105-021500.tar.gz
    sudo chown -R bunker:bunker /var/lib/bunker

    If you left the key out of the backup, put secret.key back too (or set the same BUNKER_SECRET_KEY).

  3. Start Bunker. Database migrations run automatically.

The bunker-backup.json file in the archive just describes the backup (format, Bunker version, date). You can delete it after restoring.

Admin → Updates shows the version you run, the newest release and its notes. Press Update to vX.Y.Z. Bunker then:

  1. downloads the build for its platform from the GitHub release and checks it against the release’s checksums.txt,
  2. test-runs it (bunker version) to make sure it starts on this machine,
  3. copies the database to updates/before-<version>-<time>.db in the data folder (the newest three are kept),
  4. puts the binary in bin/ in the data folder and restarts in place.

People are disconnected for a second or two; open pages reconnect by themselves. Database migrations run on start, as always. From the command line, bunker update --remote does the same for the server you’re signed in to.

This works the same on the Linux installer, Docker, Compose, Render, Railway, Fly and Azure: Bunker never rewrites its installed binary (which is often read-only), it only writes to the data folder. On start, the installed binary hands over to the one in bin/ when that one is newer. Updating the usual way later (a new image, rerunning the installer) wins: Bunker notices the installed binary has caught up and removes the copy in bin/. On a host whose data folder doesn’t survive restarts, an update from the admin page lasts until the next restart; update the image there instead.

If something goes wrong:

  • A new version that doesn’t start within three tries is dropped, and Bunker goes back to the previous one by itself. Admin → Updates says what happened.
  • Go back to vX.Y.Z on Admin → Updates switches back to the previous version and restarts. Versions only add to the database, so an older version runs fine on it. Automatic updates skip a version you went back from.

Automatic updates (off by default) install new stable releases once a day in the hour you pick (UTC). Pin them with BUNKER_UPDATE_AUTO and BUNKER_UPDATE_HOUR. BUNKER_UPDATE_SELF=false hides the update button for servers you manage only through your own pipeline; BUNKER_UPDATE_CHECK=false stops Bunker from contacting GitHub at all. Updates are recorded in the audit log (admin.update.*). Windows servers and development builds can’t update from the page: use bunker update and restart the service.

  1. Back up.
  2. Replace the binary or image:
    • Linux installer: run the same curl ... | sudo sh again (or sudo bunker update, then sudo systemctl restart bunker).
    • Docker: docker pull ghcr.io/kucukkanat/bunker and recreate the container.
    • Render, Railway, Fly: redeploy.
  3. Bunker migrates the database on start. GET /healthz returns {"ok": true, "version": "..."} when it’s ready.

Pin a version with --version v1.2.3 (installer), an image tag (ghcr.io/kucukkanat/bunker:v1.2.3) or bunkerVersion (Azure).

  • Admin (the overview page) and bunker api admin.stats: people (active today and this week), admins, apps, templates, apps in the trash, new apps this week, versions, file storage, database size, audit events, the 10 most-viewed apps (last 30 days; --days 90 for another window), the Bunker version and how many audit events streaming had to drop.
  • GET /healthz: 200 when the database answers.
  • GET /metrics: Prometheus text format (requests by status class, latency, in-flight requests, people, apps, versions, database connections, goroutines, heap, uptime, build version). Open from the machine itself (loopback), or anywhere with Authorization: Bearer $BUNKER_METRICS_TOKEN. Otherwise it answers 404.
  • Logs are JSON on stderr (BUNKER_LOG_FORMAT=text for humans, BUNKER_DEBUG=true for more). Requests slower than 2 seconds are logged.