Upgrades & rollback
Upgrade the control plane safely and roll back when you need to.
Upgrades are designed to be minimal and reversible. Every version is an image tag, and state lives in named volumes rather than in the release, so going back is a matter of recreating the container from the previous tag.
Upgrade
Pull the new signed image and recreate the container. State lives in named volumes, so your data is preserved:
docker compose pull
docker compose up -dUpdating from the console
Infrastructure → Updates shows when a new image is available and rolls it in one
click. A container can't pull and recreate itself, so this needs a small updater-agent
sidecar alongside it. Your .env already holds an AGENT_TOKEN — install.sh writes
one on every install, and the manual install generates one because the compose file
refuses to come up without it. Point the manager at the agent and start the profile:
echo "CM_UPDATER_AGENT_URL=http://veil-cm-updater:3999" >> .env
docker compose --profile updater up -dNo AGENT_TOKEN in .env?
Only possible if the file was written by something other than install.sh or the
documented manual steps. Add one with
echo "AGENT_TOKEN=$(openssl rand -hex 32)" >> .env — but check for an existing line
first, because a second one silently wins and would orphan an already-configured
agent.
The same page updates your workers. Workers on the manager's own machine need no agent; workers on other servers get one from the compose file the console generates for them.
Worker updates drain the worker first and wait for running browsers to finish before replacing the container, so an update won't kill a live session. If a new image fails its health check, the previous one is brought back automatically.
Check migrations first
Database migrations are forward-only. If you want to know what will change, diff the migrations between the two releases before deploying.
Rollback
An update that comes up unhealthy is rolled back for you. To deliberately downgrade a working install, pin the previous image tag and recreate:
VEIL_CLUSTER_MANAGER_TAG=vX.Y.Z docker compose up -dPinning the tag in .env instead makes it survive the next up -d, which is what you
want if the downgrade is meant to hold.
Migrations and rollback
If the newer version applied a migration the old code cannot tolerate, roll the database back to a pre-upgrade backup. Prefer migrations that are safe to back-level.