Upgrading

Upgrading

cd writ
git pull
docker compose up -d --build

The entrypoint runs alembic upgrade head on every boot, so schema migrations apply automatically.

Before you upgrade

Back up the data volume. Migrations move forward only — there is no downgrade path.

--build is not optional

Without it, compose reuses the existing writ-coordinator:latest image and you get the new code's migrations against the old code's application. That combination fails in confusing ways. Always --build.

Keep your .env

Never regenerate it as part of an upgrade. A new SECRET_ENCRYPTION_KEY makes every stored credential unreadable; new signing secrets invalidate sessions and issued fleet tokens, so every agent has to be re-enrolled.

If a release adds a new required variable, gen-env.sh and .env.example will name it — add just that one by hand.

Agents

Agents and the coordinator are versioned independently. Update an agent by re-running the one-line installer with WRIT_FORCE_DOWNLOAD=1, or by replacing the binary and restarting it.

An agent that is behind will usually keep working; if a release changes the wire contract, the changelog says so.

Verify

docker compose logs -f coordinator     # migrations, then "started successfully"
curl -s localhost:8000/health

Then confirm an agent is still online in Fleet, and run one workflow.