Boss Man home

Guides Set it up your way

Updating and backups

Boss Man backs up its database before every update. This guide covers updating the server and the runners, where backups go, and how to restore one.

What happens when you update: back up first, update, check it is healthy, and the way back if it is not.
An update backs up first, then updates and checks. The way back for code and the way back for data are different.

Update the server

From the install folder, run:

Run on the Linux machine, as root

cd $B/src && scripts/deploy.sh

The script backs up the database, pulls the code, rebuilds, restarts and waits for the server to report healthy. If the runners' code changed too, it asks whether to update them as well. Add --dry-run to see the steps without running them. A single server is down for about a minute while it restarts.

If there is nothing new, the script says "Nothing new to deploy" and stops before the backup, so no backup is made. Add --force to rebuild and restart anyway. It backs up first.

If the health check fails, the script prints the rollback commands and changes nothing by itself. scripts/deploy.sh --rollback puts the previous code back. It does not roll back the database.

Update the runners

Update the runners about once a week, for new Claude Code releases:

Run on the Linux machine, as root

cd $B/src && scripts/update-runner.sh

It builds a new runner image and checks it with networking off. If the check fails, the script says "The canary failed", and the runners keep the old image. If the check passes, the script also rebuilds the launcher, the part that starts each company's runner. Then the runners move to the new image:

Follow the swap in Runner update, which also has Cancel the update. To undo, run scripts/update-runner.sh --rollback.

Update from the web page (optional)

With the optional host deployer, you can update from Boss Man. The host deployer is a root script on the machine, run every minute by cron. Setting it up is in docs/06-install-truenas.md, section 9a, and works on any Linux host.

Once it is set up:

Deploy and Deploy latest update the server only, never the runners. When an update changes the runners' code, the Deploy card says so, and Boss Man raises a second card later to update the runners. You can also choose Build and update runners yourself.

The host deployer will not apply changes to these files:

Apply those by hand with scripts/deploy.sh.

Where backups are kept

Backups go in the install folder, next to src, unless you set BOSSMAN_BACKUP_DIR. Only their owner can read them.

Check a backup restores

Run on the Linux machine, as root

cd $B/src && scripts/restore-test.sh --fresh-backup

It makes a new backup and loads it into a throwaway database. The live database is not touched. The last line must start with OK:. To test an older backup, give its file name instead of --fresh-backup.

Restore the live database

Do this only when an update has damaged the data. A restore replaces the live data and loses everything written after the backup. If only the code is wrong, use scripts/deploy.sh --rollback instead, which never touches the data.

Run every command as root from $B/src. These steps are for a single-server install. For blue/green, follow docs/06-install-truenas.md.

  1. Test the backup you chose on the throwaway database with scripts/restore-test.sh ../bossman-YYYY-MM-DD-HHMM.sql.gz. The output must end with a line starting OK:. If it does not, choose another file.
  2. Stop the server so nothing writes: docker compose stop server.
  3. Keep a copy of the current data, in case the restore was the wrong call: docker compose exec -T db pg_dump -U bossman bossman | gzip > ../before-restore-$(date +%F-%H%M).sql.gz.
  4. Replace the live database. First run docker compose exec -T db psql -U bossman -d postgres -c 'DROP DATABASE bossman' -c 'CREATE DATABASE bossman OWNER bossman'. If it says the database is "being accessed by other users", go back to step 2. Then run gunzip -c ../bossman-YYYY-MM-DD-HHMM.sql.gz | docker compose exec -T db psql -v ON_ERROR_STOP=1 -q -U bossman -d bossman.
  5. Start Boss Man again: docker compose up -d.

Keep the master key safe

secrets/master.key encrypts every secret Boss Man stores. Keep a copy off the machine. A database backup without the master key restores everything except your stored secrets.

Export a company

Settings > Import and export downloads a company as <company>.bossman.zip, with its wiki and its open or all tickets if you choose. Secret values, logins, runs and costs are never exported. An import always makes a new company, with every agent paused and no secrets.

Something wrong or missing? Tell us on GitHub.