Applying Updates

An update always has two parts: new container images and — if the data model changed — database migrations. The bundled deploy script does both, in the right order.

The principle

Images are not built on the server. They are pulled from the container registry at the version set in deployment/.env under IMAGE_TAG. So an update is always: set the new tag → run the deploy script.

Procedure

cd deployment

# 1. Set the target version (example)
#    IMAGE_TAG=0.1.0-alpha.16
nano .env

# 2. Deploy
bash scripts/deploy.sh

The script does:

Step	What happens
1	Check prerequisites — Docker, Compose, configuration present
2	Database snapshot — a full dump before any change
3	Pull images — docker compose pull at the new IMAGE_TAG
4	Migrations — alembic upgrade head. If a migration fails the script aborts and the running version is left untouched.
5	Replace containers — docker compose up -d
6	Health check — waits until the health endpoint responds again

The application is briefly unavailable (typically 10–30 seconds) while containers are replaced. Zero-downtime updates would need several instances behind a load balancer — not part of the delivered scope.

Verify after the update

curl -s https://<your-domain>/api/health
# expected: {"status":"ok","database":"connected","storage":"connected"}

And in the browser: the start page loads, sign-in works, an existing run is unchanged.

Rolling back

There are two separate cases — do not mix them up:

a) Roll back the application version only

If the new version is faulty but the data is fine:

# set the previous tag in deployment/.env
#    IMAGE_TAG=0.1.0-alpha.15
bash scripts/deploy.sh

Careful with migrations

This works only if the update contained no database migration — otherwise the old code no longer matches the new schema. If it did, you need case (b).

b) Roll the database back to the pre-update state

bash scripts/deploy.sh --rollback

The script asks for confirmation and restores the snapshot taken right before the deploy. Afterwards set the old IMAGE_TAG as in (a) and deploy again, so code and schema match.

Data loss

A database rollback discards everything created since the snapshot — submissions, scores, chat messages. During a live event this is usually the worse option: first check whether the problem can be fixed forwards.

Backups

Before every deploy the script takes a snapshot automatically; the dumps live in deployment/backups/ and are kept for 30 days. How to secure and restore them independently: see Database.