Upgrading and backing up Wharfbase

Upgrading

Knowing when. Once a day, Wharfbase asks the license server for the latest release (it sends nothing with the question). When a newer one is out, admins see it in the sidebar and under Settings → General, with a link to its notes, and wb doctor warns about it. A pre-release is only offered to a pre-release. Settings → General → Check now asks right away; the switch there, or WB_UPDATE_CHECK=false, turns it off.

wharfbase upgrade

This fetches the newest release of the version you installed (WB_VERSION in /opt/wharfbase/.env: latest, or a pinned 1.4 or 1.4.2), pulls the images and restarts. Data, settings, saved connections and the networks Wharfbase had joined are kept.

Without the installer: docker compose pull && docker compose up -d in the folder with your compose file.

Several servers: upgrade the hub first. Agents may run one minor version behind the hub, so upgrade them afterwards.

Migrations: when a release changes the format of Wharfbase’s own database, the first start after the upgrade migrates it.

• It copies the database to /data/backups/pre-migrate-v<old>-<time>.db first, and keeps the last 5 copies.
• If a migration fails, Wharfbase stops and leaves the copy.

Going back to an older release isn’t supported: a newer data folder makes an older Wharfbase refuse to start (SCHEMA_TOO_NEW). To downgrade, restore the pre-migrate copy as /data/wharfbase.db while Wharfbase is stopped.

What to back up

What	Where (installer)	Why
The master key	/opt/wharfbase/secrets/master.key	It encrypts every stored database password. Without it, a backup of the data can’t be read.
The data volume	the wharfbase_data volume (/data in the container)	Wharfbase’s database: users, connections, saved queries, views, the audit log; database backups (Pro) under backups/
Your settings	/opt/wharfbase/.env	The WB_* variables you changed

Keep the master key apart from the data backups. With only the data, nobody can read the stored passwords; with both, they can.

With the store in PostgreSQL (WB_STORE_URL, see High availability), Wharfbase’s database is there: back it up with your PostgreSQL backups. The data volume then holds only temporary files, and the shared volume (WB_SHARED_DIR) holds the database backups and the agents’ hub key.

Taking a consistent copy

Wharfbase’s database is SQLite in WAL mode: copy it while Wharfbase is stopped, which takes seconds.

wharfbase down
docker run --rm -v wharfbase_data:/data -v "$PWD":/out alpine tar czf /out/wharfbase-data.tgz -C /data .
wharfbase up

One-click templates (Coolify, Dokploy, Portainer, CasaOS, Unraid) keep the master key inside the data volume. A backup of that volume is enough to restore, so keep it private.

Moving to another server

1. Stop Wharfbase on the old server.
2. Copy the data volume and the master key over, then start Wharfbase on the new one.
3. Discovery re-finds the databases on the new host; saved connections keep their passwords.
4. A license key bound to the old instance can be moved from your account page.