Quickstart

Wharfbase runs as two containers next to your databases: wharfbase (the app) and wharfbase-socket-guard (the only one that touches the Docker socket, and only for the calls listed in What Wharfbase reads).

You need a Linux server with Docker 24+ and Docker Compose 2.24+. macOS with Docker Desktop, OrbStack or Colima works for trying it out.

1. Install

curl -fsSL https://fleeq.net/wharfbase/get | sh

As root this installs into /opt/wharfbase and adds a wharfbase command to /usr/local/bin. Without root, you need to be in the docker group, and it installs into ~/wharfbase and ~/.local/bin. The script never installs Docker itself.

When it finishes it prints the address and a setup token:

Wharfbase is running.

  Open         http://203.0.113.10:8480/setup
  Setup token  hA9rvpLV6kOrp1tU43zwqkm-FP6kwa6a

Common options (sh -s -- --help lists them all):

Option	For
--port 9000	another host port (default 8480)
--bind 127.0.0.1	only reachable locally, e.g. behind a reverse proxy (Traefik)
--public-url https://db.example.com	the address people use, when it isn’t http://<server IP>:<port>
--host-scan	also find databases installed on the host itself, not in Docker (read-only)
--no-network-attach	never join other Docker networks (some databases stay unreachable)
--version 1.2.3	a specific release (default latest)
--dir /srv/wharfbase	another install directory

For example: curl -fsSL https://fleeq.net/wharfbase/get | sh -s -- --bind 127.0.0.1 --public-url https://db.example.com

2. Set up

Open the printed address, paste the token and create the owner account. Lost the token? wharfbase setup-token prints it again. Within seconds the dashboard lists every database it found, with the container, engine and version, where its data lives, which services use it, and anything that needs attention. Next: connect, browse and query.

Back up /opt/wharfbase/secrets/master.key. It encrypts the database passwords Wharfbase stores. Without it, a backup of the data can’t be decrypted.

3. Day to day

wharfbase status      # containers and health
wharfbase logs        # follow the logs
wharfbase upgrade     # newest release of the configured version; data and settings are kept
wharfbase down / up   # stop / start (also applies changes to /opt/wharfbase/.env)
wharfbase uninstall   # remove the containers, keep data and secrets
wharfbase uninstall --purge   # remove everything (asks you to type "delete")

The same command runs the CLI on the server, signed in as the owner: wharfbase ls, wharfbase inspect pg17, wharfbase query pg17 "SELECT 1", wharfbase shell pg17. From another machine, npm i -g wharfbase and wb login. All commands: The wb CLI.

Settings you’d change by hand live in /opt/wharfbase/.env (all WB_* variables: reference §A). Run wharfbase up after editing it.

Without the installer

The installer only automates this:

mkdir -p /opt/wharfbase/secrets && cd /opt/wharfbase
curl -fsSLO https://fleeq.net/wharfbase/get/latest/docker-compose.yml
head -c 32 /dev/urandom | base64 > secrets/master.key
chown 10001:10001 secrets/master.key && chmod 0400 secrets/master.key
docker compose up -d
docker exec wharfbase wb setup-token

Put WB_PUBLIC_URL, WB_PORT or WB_BIND in a .env file next to the compose file if you need them.

One-click templates for Unraid, CasaOS, Coolify, Dokploy and Portainer are in deploy/templates.

Troubleshooting

• “Docker API unreachable” in the logs: the socket-guard isn’t running (wharfbase status), or the Docker socket isn’t at /var/run/docker.sock. For rootless Docker, the installer writes the right path as WB_DOCKER_SOCKET in .env.
• A database shows “needs network” and auto-join is off: open it and use Join network, or set the attach mode to Auto under Settings → Discovery.
• A database on the host shows “needs host config”: it only listens on 127.0.0.1. The Reachability tab shows the exact line to change.
• “Wharfbase’s data volume has only … MB free, so changes are paused”:
  • Below 64 MB free (WB_MIN_FREE_MB), Wharfbase stops saving changes before a write could fail half-way.
  • Browsing, signing in and deleting old backups still work.
  • Free some space (old backups and exports are in the data folder) and carry on; nothing needs a restart.
• Wharfbase won’t start: “The master key does not match this data directory”, or the key “must be 32 random bytes”:
  • The key file was changed or damaged. Wharfbase refuses to start rather than make a new key, and touches nothing.
  • Put back the key you backed up (step 2) and start it again.
• Docker restarted, or a database restarted mid-query:
  • A scan that loses Docker halfway keeps what it knew and says the scan failed; the next scan (automatic once Docker is back) catches up.
  • A query whose connection drops ends with an error, and the next one reconnects.
• Everything else: Settings → Diagnostics (or wharfbase doctor) checks Docker, the guard, networks, the data directory and the master key, and says what to fix. wharfbase doctor --bundle writes a redacted zip to send with a support request.