Deploying Loom

A deploy changes what every user of the deployment is served. Run it only on an explicit request, from the deployment's own checkout. .claude/settings.json denies an agent ./redeploy.sh, its --force and --rollback, and every docker command on the deployment's containers, reads included: print each one for the operator to run, and read its output back.

1. Preflight

./redeploy.sh --status                         # which colour serves, which build, what is idle
git status --short                              # tracked edits ship with the build: each one is a question
git fetch -q origin main && git log --oneline HEAD..origin/main   # what this deploy brings
LOOM_COLOUR=blue LOOM_COLOUR_PORT=7781 docker compose --env-file .env -f dev/docker-compose.colour.yml config -q   # a broken .env edit fails here, not mid-swap

• Another deploy in flight (an idle colour starting, a held lease, someone else's announced cut): wait. Two swaps at once can leave the proxy on a colour that is about to stop.
• Read what the incoming commits change: new migrations (additive, applied at boot by the new colour while the old one serves), new settings that need .env values, a re-index or a worker change the PR body announced.
• Never start throwaway containers with the deployment's names (loom-blue, loom-green, loom-proxy, loom-server, loom-workers, loom-*-workers); a cleanup of the throwaway then stops production.

2. Swap

./redeploy.sh            # builds and boots the idle colour, waits for status=ok, readiness.ready and schema.pending=[], swaps the proxy, stops the old colour

The script refuses to swap when the new colour is unhealthy or not ready, a provider is degraded, or the embedding width does not match; read its last !!! line rather than forcing. Both colours serve on the new schema for a moment, which is safe only because every change follows the rolling-upgrade rules. The workers lease passes between colours; if the script exits before the new colour's workers take over, it restarts the old colour's.

3. After the swap

curl -s localhost:7777/v1/health | jq '{status, build_commit, ready: .readiness.ready, schema: .schema.pending, providers_degraded}'
# for the operator, with the serving colour from --status:
docker logs --since 5m loom-<colour> 2>&1 | grep -iE 'error|traceback' | tail

• build_commit is the commit you meant to deploy. The script fetched origin/main and rebased onto it (--autostash), refused a dirty tree that was behind, and asked [y/N] before pulling commits that touch the deploy files; a dirty tree it was not behind ships as it is.
• Watch error rate and p95 for the first minutes; a ClickHouse replica restarting at the same moment slows inserts without a code cause.

4. Rollback

./redeploy.sh --rollback

The previous colour restarts on its previous image and takes the traffic; the current colour keeps running until the operator confirms the rollback and stops it with the command the script prints (docker stop -t 75 loom-<colour>). No schema step, because migrations are additive (upgrades). Rows the new build wrote stay.

Reference

Deployment, upgrades, troubleshooting.