Skip to main content

Rollback & Environment Recovery

When a deploy goes wrong, you have two tools: roll the image back to a known-good version, or, in the worst case, tear the environment down and let CI rebuild it. Both are straightforward — with one important caveat about the database.

Rolling back to a previous version​

On the server, in the environment directory, set VERSION to the previous tag, pull, and bring the stack up:

cd /app/production
export VERSION=v0.16.0
docker compose -p production --env-file .env -f deploy/docker-compose.prod.yml pull
docker compose -p production --env-file .env -f deploy/docker-compose.prod.yml up -d

Then verify with ... ps and the API health check. (Use -p staging / VERSION=staging-latest for staging.)

The forward-only caveat​

Rolling the image back does not roll back the database schema — migrations are forward-only. So a rollback restores the code, not the data model. If a bad deploy included a migration, plan accordingly: a code rollback runs the old image against the new schema, which is usually fine for additive migrations but must be reasoned about for anything that changed or removed structure.

Tearing down and rebuilding​

To wipe an environment and start clean:

cd /app/staging
docker compose -p staging --env-file .env -f deploy/docker-compose.prod.yml down -v   # WARNING: destroys the database
rm -rf deploy/ plugins/ scripts/ api/     # keep .env / n8n.env unless you want a totally clean slate

The next deploy from CI recreates everything, initializing the database from deploy/init-db/001_schema.sql. To confirm a full teardown, check that no containers, networks, or volumes for that environment remain (docker ps -a, docker network ls, docker volume ls), and docker network prune / docker volume prune any orphans.

The shared Caddy is separate — only tear it down (docker compose -f /app/deploy/docker-compose.caddy.yml down -v) if you're removing all environments, since it fronts both.