Backups and upgrades
What’s in the data folder
Section titled “What’s in the data folder”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 |
Back up
Section titled “Back up”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.
Download one now
Section titled “Download one now”curl -X POST -H "Authorization: Bearer $TOKEN" -OJ \ https://bunker.example.com/api/v1/admin/backup# saves bunker-backup-20261105-021500.tar.gzOr 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.
Scheduled snapshots
Section titled “Scheduled snapshots”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 |
BUNKER_BACKUP_DIR=/mnt/backups/bunkerBUNKER_BACKUP_EVERY=12hBUNKER_BACKUP_KEEP=14- Files are named
bunker-YYYYMMDD-HHMMSS.tar.gz(UTC) and always includesecret.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:
bunker api admin.backups.list # {"enabled": true, "dir": "...", "every": "12h0m0s", "keep": 14, "backups": [...]}bunker api admin.backups.run # writes one nowBy hand
Section titled “By hand”Without Bunker’s help, take a consistent database copy plus the files:
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.
With the CLI
Section titled “With the CLI”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.
bunker backup /backup/bunker-$(date +%F).tar.gzRestore
Section titled “Restore”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.
sudo systemctl stop bunkersudo -u bunker BUNKER_DATA_DIR=/var/lib/bunker bunker restore /backup/bunker-2026-11-05.tar.gzsudo systemctl start bunkerBy hand
Section titled “By hand”-
Stop Bunker.
-
Unpack the backup into an empty data folder:
Terminal window sudo mkdir -p /var/lib/bunker && cd /var/lib/bunkersudo tar -xzf /mnt/backups/bunker/bunker-20261105-021500.tar.gzsudo chown -R bunker:bunker /var/lib/bunkerIf you left the key out of the backup, put
secret.keyback too (or set the sameBUNKER_SECRET_KEY). -
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.
Upgrade
Section titled “Upgrade”From the admin page
Section titled “From the admin page”Admin → Updates shows the version you run, the newest release and its notes. Press Update to vX.Y.Z. Bunker then:
- downloads the build for its platform from the GitHub release and checks it against the release’s
checksums.txt, - test-runs it (
bunker version) to make sure it starts on this machine, - copies the database to
updates/before-<version>-<time>.dbin the data folder (the newest three are kept), - 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.
By hand
Section titled “By hand”- Back up.
- Replace the binary or image:
- Linux installer: run the same
curl ... | sudo shagain (orsudo bunker update, thensudo systemctl restart bunker). - Docker:
docker pull ghcr.io/kucukkanat/bunkerand recreate the container. - Render, Railway, Fly: redeploy.
- Linux installer: run the same
- Bunker migrates the database on start.
GET /healthzreturns{"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).
Monitoring
Section titled “Monitoring”- 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 90for another window), the Bunker version and how many audit events streaming had to drop. GET /healthz:200when 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 withAuthorization: Bearer $BUNKER_METRICS_TOKEN. Otherwise it answers 404.- Logs are JSON on stderr (
BUNKER_LOG_FORMAT=textfor humans,BUNKER_DEBUG=truefor more). Requests slower than 2 seconds are logged.