Breadbox never updates itself. When a newer release is published on GitHub, the admin dashboard shows a “new release available” notice in the sidebar and an update badge under Settings → System — you decide when to apply it. This keeps you in control of update timing, which matters for a self-hosted financial app.
Updating is safe and non-destructive:
- Your
.env (including ENCRYPTION_KEY) is never touched.
- Your PostgreSQL data is preserved — the database lives in its own volume.
- Database migrations run automatically the next time Breadbox starts.
Want to know what changed before you update? Every release is summarized in the changelog, and full release notes live on the GitHub releases page. Before you update
Updating won’t delete anything, but a backup is cheap insurance — especially across a major version:
- Back up your
.env if you haven’t already. Losing ENCRYPTION_KEY makes stored bank credentials unrecoverable. See Install → Back up your .env.
- Snapshot the database from Settings → Backups in the dashboard, or with
pg_dump if you manage Postgres yourself. See Backup & restore.
Update by install method
Pick the tab that matches how you installed Breadbox.
The curl … | bash installer writes a docker-compose.prod.yml into your install directory and drives Compose with -f. Run these from that directory:cd ~/.breadbox # or /opt/breadbox for a root install
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d
docker compose --profile caddy -f docker-compose.prod.yml pull
docker compose --profile caddy -f docker-compose.prod.yml up -d
pull fetches the new image; up -d recreates the container on it. Migrations run on boot. Existing containers that don’t change are left running.Not sure where you installed? Root installs land in /opt/breadbox; regular-user installs in $HOME/.breadbox. The directory holds your docker-compose.prod.yml and .env.
If you added Breadbox to your own Compose stack (the file is typically named docker-compose.yml), the bare commands work:cd /path/to/your/stack
docker compose pull
docker compose up -d
docker compose --profile caddy pull
docker compose --profile caddy up -d
Download the new binary for your platform, replace the old one, and restart the process. Migrations run on the next start.# Linux amd64 example — swap for your platform
curl -fsSL https://github.com/canalesb93/breadbox/releases/latest/download/breadbox-linux-amd64 -o breadbox.new
chmod +x breadbox.new
mv breadbox.new breadbox # replace the running binary
# restart however you run it — e.g. systemd:
sudo systemctl restart breadbox
DATABASE_URL and ENCRYPTION_KEY environment variables stay the same — point the new binary at the same database and it picks up where it left off. Pull the latest code, reinstall, and restart:cd breadbox
git pull
go install ./cmd/breadbox
# restart your running process (systemd, a terminal, etc.)
breadbox (not github.com/...), so update by pulling the repo as shown — go install …@latest against the GitHub path is not supported. Pin a specific version
By default docker-compose.prod.yml tracks a pinned release tag. To move to (or hold) a specific version, edit the image: line:
image: ghcr.io/canalesb93/breadbox:v0.1.0
pull / up -d pair for your install method above. To track the latest release on every pull instead (not recommended for production), use :latest.
Verify the update
After up -d (or a restart) completes:
-
Reload the dashboard — the “new release available” notice should be gone.
-
Check Settings → System — the version badge should show the new version and read Up to date.
-
Optionally confirm from the shell:
# Docker install:
docker compose -f docker-compose.prod.yml exec breadbox breadbox version
docker compose -f docker-compose.prod.yml exec breadbox breadbox doctor
# Binary / source install:
breadbox version
breadbox doctor
breadbox doctor is read-only and re-validates your config, database, migrations, and encryption key.
Rolling back
If a release misbehaves, pin the previous tag and re-pull:
image: ghcr.io/canalesb93/breadbox:v0.0.9 # previous version
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d
Rolling back the application does not roll back database migrations. Breadbox migrations are additive and forward-compatible within a minor series, so a one-step rollback is normally fine — but if you need to revert across a major version, restore the database snapshot you took before updating. Unattended updates
Breadbox deliberately ships no auto-update logic. If you want hands-off updates anyway, run a separate updater alongside it — Watchtower or Diun — or a simple cron job:
0 3 * * * cd /opt/breadbox && docker compose -f docker-compose.prod.yml pull && docker compose -f docker-compose.prod.yml up -d >> /var/log/breadbox-update.log 2>&1
Last modified on June 6, 2026
