Upgrading SPOT¶
SPOT does not apply updates for you. The dashboard's System -> Updates page (admin-only) checks Codeberg daily for new releases of the deploy repo and surfaces a banner with the upgrade command. The operator runs the command ; that is the only supported path.
Standard upgrade¶
From your install directory (the default is /opt/spot):
cd /opt/spot
git pull # fetch new docker-compose.yml + version pins
docker compose pull # download the new images
docker compose up -d
git pull is what propagates infrastructure version bumps (Traefik, Postgres, Redis, RabbitMQ) and any new services or environment variables. Without it, docker compose pull only refreshes existing image tags.
If you installed SPOT by cloning the deploy repo, this is the full upgrade.
If you installed by docker pull only (no git), skip git pull and run the last two commands. You only get image refreshes; new infrastructure pins or new services in a release will not land. Re-clone the deploy repo if you want them.
Database migrations run automatically on the next docker compose up -d via the migration service.
Always back up first¶
Updates can fail. Take a Postgres dump before every upgrade:
The dashboard's update page repeats this command and warns prominently before each upgrade.
Local customisations: docker-compose.override.yml¶
docker-compose.yml is part of the deploy repo and is overwritten by git pull. Editing it means your edits will be lost on every upgrade, and git pull will fail with a merge conflict if you edit and then try to upgrade.
The supported way to customise the stack is docker-compose.override.yml next to docker-compose.yml. Compose merges the two automatically (docker-compose.override.yml is loaded by default, no flag required), and the deploy repo does not track it ; it survives every git pull.
Example: bind an extra volume into the api-gateway container.
Apply with docker compose up -d. The merged config is visible with docker compose config.
The dashboard runs an automatic check: it SHA-compares the local docker-compose.yml against the upstream copy at the running version. If they differ, the System Updates page shows a red banner reminding you to move the customisation into docker-compose.override.yml before pulling.
Pin a specific version¶
To stay on a specific version instead of upgrading, set the pins in your .env:
These override the defaults from docker-compose.yml. git pull still runs cleanly; it just changes the defaults under your overrides.
Rollback¶
To roll back to a previous deploy release:
Or, if migrations ran and you need the old database too: stop the stack, restore the pre-upgrade backup, then check out the old version and start again.
docker compose down
cat spot-backup-20260430.sql | docker compose exec -T postgres psql -U spot spot
git checkout v1.0.0
docker compose up -d
Migrations are forward-only. A roll-forward to the new version + a forward migration is recoverable; a rollback after a migration is only safe if you have a backup.
Disabling the update notification¶
The dashboard banner and the System -> Updates page can be turned off:
Then docker compose up -d api-gateway. The endpoint disappears and no Codeberg traffic is generated.
Release notes¶
See the deploy releases for release history and migration notes.