loom-deploy

Exact captured content · path .claude/skills/loom-deploy/SKILL.md · sha256 7a4af238dabf54d8… · revision e50ca4a235d7b8329193ca46f28fda2653cfefc0

Download the exact captured file

---
name: loom-deploy
description: Operator procedure for a blue/green Loom deployment with redeploy.sh — preflight, swap, post-swap checks, rollback. Use only when an operator explicitly asks to deploy, roll back or check which build is serving.
disable-model-invocation: true
argument-hint: "[--status | --rollback]"
metadata:
  internal: true
---

# 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

```bash
./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

```bash
./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](../../../docs/architecture/rolling-upgrades.md). 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

```bash
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

```bash
./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](../../../docs/operations/upgrades.md#rollback)). Rows the new build wrote stay.

## Reference

[Deployment](../../../docs/operations/deployment.md#zero-downtime-pair), [upgrades](../../../docs/operations/upgrades.md), [troubleshooting](../../../docs/operations/troubleshooting.md).