refactor(deploy): drop the migrate service and image

The backend migrates itself at boot, so the migrate Dockerfile target,
compose service, and the Swarm playbook's post-deploy migration task
(plus its attachable-network requirement) all go away. Two images
remain: runtime and web. The worker now waits for the backend
healthcheck so it never touches a pre-migration schema.

Verified on a wiped stack: virgin database boots, backend logs
'database migrations applied' before listening, Sales Inquiry Pipeline
runs to execution_completed over live SSE, rate limiter returns 429
past the budget.

Author: librowski-synergy

CLAUDE.md

@@ -11,7 +11,7 @@ Three onboarding paths (A, B local-run; C docs-only). README "Get started" is th
 | `pnpm preflight`             | both | Verify Node / pnpm / Docker / ports / `.env` files. Add `--json` for agents |
 | `pnpm dev` / `pnpm dev:demo` | A    | Demo (UI only, port 4200). No backend, no Docker                            |
 | `pnpm infra:up`              | B    | Start Postgres + Temporal in Docker. Required before backend/worker         |
-| `pnpm -F backend db:migrate` | B    | Apply Drizzle migrations. First run, or after schema changes                |
+| `pnpm -F backend db:migrate` | B    | Apply Drizzle migrations out-of-band (backend also auto-migrates on boot)   |
 | `pnpm dev:ai-studio`         | B    | Full stack: infra + backend (3001) + worker + AI Studio frontend (4201)     |
 | `pnpm dev:backend`           | B    | Backend only (debug). Needs infra up                                        |
 | `pnpm dev:worker`            | B    | Execution worker only (debug). Needs infra up                               |
@@ -22,7 +22,7 @@ Three onboarding paths (A, B local-run; C docs-only). README "Get started" is th
 | `pnpm test`                  | -    | Run tests in `packages/sdk` and `packages/execution-core`                   |
 | `pnpm check`                 | -    | Lint + typecheck + format + knip                                            |
 
-Path A is UI-only and does not need Docker. Path B requires `pnpm infra:up` before backend/worker can start, and `db:migrate` on the first run.
+Path A is UI-only and does not need Docker. Path B requires `pnpm infra:up` before backend/worker can start; the backend applies pending migrations automatically at boot.
 
 ### Agent signals
 
@@ -44,7 +44,7 @@ Long-running processes already emit stable log lines that scripts and agents can
 tools/              - Root dev scripts: preflight, setup:env, infra wait
   deployment/       - Swarm/Ansible deploy path mirroring the workflow-builder repo (ACR, Traefik)
 deploy/
-  ai-studio/        - Production deployment: Dockerfile (runtime/migrate/web), compose, nginx, README
+  ai-studio/        - Production deployment: Dockerfile (runtime/web), compose, nginx, README
 apps/
   demo/             - Reference app consuming the SDK (React + Vite, port 4200)
   ai-studio/        - Reference AI workflow product (React + Vite, port 4201)

deploy/ai-studio/Dockerfile

@@ -3,9 +3,12 @@
 # AI Studio execution stack — single Dockerfile, multiple targets:
 #
 #   runtime  -> backend + execution-worker (command chosen per compose service)
-#   migrate  -> one-shot Drizzle migration runner (needs backend devDependencies)
 #   web      -> nginx serving the AI Studio SPA + reverse proxy to the backend
 #
+# Database migrations run inside the backend at boot (drizzle-orm's
+# programmatic migrator over apps/backend/drizzle/), so there is no separate
+# migration image or deploy step.
+#
 # Build context must be the repo root (workspace packages are linked via
 # pnpm `workspace:*`), e.g.:
 #
@@ -51,13 +54,6 @@ RUN --mount=type=cache,id=pnpm-store,target=/pnpm/store \
 #   backend: pnpm --filter backend start:prod
 #   worker:  pnpm --filter execution-worker start:prod
 
-# Migrations need drizzle-kit, a backend devDependency — hence a separate
-# target with a dev install. Runs as a one-shot service before the backend.
-FROM source AS migrate
-RUN --mount=type=cache,id=pnpm-store,target=/pnpm/store \
-    pnpm install --frozen-lockfile --prefer-offline --filter backend...
-CMD ["pnpm", "--filter", "backend", "db:migrate"]
-
 # The SPA build imports the SDK from source (vite alias), so this needs the
 # full frontend dependency tree. VITE_BACKEND_URL is baked in at build time;
 # the default (empty) makes the app call /api on its own origin, which the

deploy/ai-studio/README.md

@@ -14,15 +14,16 @@ any Docker host — an Azure VM, AWS, on-prem — with no cloud-specific glue.
 | `web`         | `ai-studio-web` (nginx)        | Serves the SPA, proxies `/api` to the backend   | `${WEB_PORT}` (only one) |
 | `backend`     | `ai-studio-runtime`            | Hono REST + SSE event stream                    | internal                 |
 | `worker`      | `ai-studio-runtime`            | Temporal worker, makes the OpenRouter LLM calls | internal                 |
-| `migrate`     | `ai-studio-migrate`            | One-shot Drizzle migrations, then exits         | internal                 |
 | `temporal`    | `temporalio/auto-setup` pinned | Workflow engine                                 | internal                 |
 | `app-db`      | `postgres:16`                  | Workflow snapshots + execution events           | internal                 |
 | `temporal-db` | `postgres:16`                  | Temporal's own state store                      | internal                 |
 | `temporal-ui` | `temporalio/ui` pinned         | Debug only (`--profile debug`)                  | `127.0.0.1:8233`         |
 
-All images build from one Dockerfile (`deploy/ai-studio/Dockerfile`) with the
+Both images build from one Dockerfile (`deploy/ai-studio/Dockerfile`) with the
 repo root as context. Backend and worker share a single image and differ only
-in the compose `command`.
+in the compose `command`. Database migrations are applied by the backend at
+boot (drizzle-orm's programmatic migrator) — there is no separate migration
+service or step.
 
 ## Quick start
 
@@ -32,9 +33,9 @@ cp .env.example .env        # set OPENROUTER_API_KEY
 docker compose up -d --build
 ```
 
-First boot: migrations run automatically (`migrate` exits 0, then the backend
-starts). The worker crash-loops for ~30s until Temporal finishes auto-setup —
-that's expected, `restart: unless-stopped` converges it.
+First boot: the backend applies migrations and only then starts serving (its
+healthcheck gates the worker). The worker crash-loops for ~30s until Temporal
+finishes auto-setup — that's expected, `restart: unless-stopped` converges it.
 
 Verify:
 
@@ -89,7 +90,7 @@ Swapping the LLM is a one-liner: change `AI_MODEL` to any
 ```bash
 docker compose logs -f backend worker        # tail the apps
 docker compose --profile debug up -d         # Temporal UI on 127.0.0.1:8233
-docker compose up -d --build                 # deploy a new version (re-runs migrations)
+docker compose up -d --build                 # deploy a new version (backend re-applies migrations at boot)
 docker compose down                          # stop (volumes survive)
 docker exec ai-studio-app-db-1 pg_dump -U wb workflow_builder > backup.sql
 ```

deploy/ai-studio/ai-studio-deployment.decision-log.md

@@ -32,7 +32,7 @@ Everything lives in `deploy/ai-studio/`: one multi-target Dockerfile, a
 production `docker-compose.yml`, the nginx config, `.env.example`, and a
 DevOps-facing README.
 
-1. **One Dockerfile, three targets** (`runtime`, `migrate`, `web`), built
+1. **One Dockerfile, two targets** (`runtime`, `web`), built
    with the repo root as context (pnpm `workspace:*` links require it). A
    shared `source` stage does `pnpm fetch` against a BuildKit cache mount, so
    per-target installs are store-hits.
@@ -44,11 +44,13 @@ DevOps-facing README.
    entirely — there is no bundling step to get wrong.
 3. **One shared `runtime` image for backend and worker**; the compose
    `command` picks the entrypoint. One image to build, push, and version.
-4. **Migrations as a one-shot compose service** (`migrate` target, carries
-   drizzle-kit as a backend devDependency). `depends_on:
-service_completed_successfully` gates the backend, so `docker compose up`
-   is a complete first boot. Same answer works as a k8s Job / ACA job if a
-   customer reshapes the topology.
+4. **Migrations on backend boot** (revised 11.06.2026 — originally a
+   one-shot `migrate` compose service). The backend applies pending Drizzle
+   migrations via drizzle-orm's programmatic migrator before accepting
+   traffic; on failure it exits and the restart policy retries until
+   Postgres answers. One less image, no orchestrator-specific ordering —
+   the same behavior on compose, Swarm, or anything else. Single-replica
+   assumption: concurrent backends would race the migrator.
 5. **nginx is the only public surface.** It serves the SPA and proxies
    `/api` to the backend on the internal network; the SSE stream route gets
    `proxy_buffering off` + long read timeout. The backend container is
@@ -135,6 +137,12 @@ Found and fixed during end-to-end verification: the worker ignored
   - pnpm version is pinned in two places (root `packageManager` +
     Dockerfile).
 
+## Revisions
+
+- **11.06.2026** — `migrate` target and service removed; the backend now
+  migrates itself at boot (Jan's simplification request during WB-229
+  review). Dockerfile is down to two targets (`runtime`, `web`).
+
 ## Status
 
 Accepted

deploy/ai-studio/docker-compose.yml

@@ -73,19 +73,8 @@ services:
       - '127.0.0.1:8233:8080'
     restart: unless-stopped
 
-  migrate:
-    image: ai-studio-migrate
-    build:
-      context: ../..
-      dockerfile: deploy/ai-studio/Dockerfile
-      target: migrate
-    environment:
-      DATABASE_URL: postgresql://wb:${APP_DB_PASSWORD:-wb}@app-db:5432/workflow_builder
-    depends_on:
-      app-db:
-        condition: service_healthy
-    restart: 'no'
-
+  # Applies Drizzle migrations at boot, before accepting traffic. A failure
+  # (e.g. Postgres still starting) exits the process and `restart` retries.
   backend:
     image: ai-studio-runtime
     build: *runtime-build
@@ -106,8 +95,6 @@ services:
     depends_on:
       app-db:
         condition: service_healthy
-      migrate:
-        condition: service_completed_successfully
       temporal:
         condition: service_started
     healthcheck:
@@ -138,8 +125,9 @@ services:
     depends_on:
       app-db:
         condition: service_healthy
-      migrate:
-        condition: service_completed_successfully
+      # healthy = migrations applied — the worker writes to the same schema
+      backend:
+        condition: service_healthy
       temporal:
         condition: service_started
     restart: unless-stopped

tools/deployment/README.md

@@ -5,7 +5,7 @@ the same layout, scripts, and Ansible flow as the `workflow-builder` repo's
 `tools/deployment/` — so DevOps operates one familiar shape.
 
 This is an **orchestration overlay, not a second deployment**: it consumes
-the exact same three images (`runtime`, `migrate`, `web`) built from
+the exact same two images (`runtime`, `web`) built from
 [`deploy/ai-studio/Dockerfile`](../../deploy/ai-studio/Dockerfile). The
 compose file in `deploy/ai-studio/` remains the portable, customer-facing
 artifact and the local full-stack runner; this directory adds the
@@ -17,7 +17,7 @@ tools/deployment/
 │   ├── build-docker.sh    # build all 3 targets, tag for ACR, push (CI-gated)
 │   └── deploy.sh          # run the Ansible playbook (CI image or workstation)
 └── ansible/deploy-application/
-    └── main.yml           # writes the Swarm stack file on the master + deploys + migrates
+    └── main.yml           # writes the Swarm stack file on the master + deploys
 ```
 
 ## Usage
@@ -52,13 +52,12 @@ make them runnable from a workstation or GitHub Actions.
 
 ## What differs from the workflow-builder playbook (and why)
 
-| Deviation                                                                                         | Reason                                                                                                                               |
-| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| Postgres ×2 + Temporal services with named volumes, pinned via `node.labels.ai-studio-data==true` | AI Studio is stateful; Swarm volumes are node-local. **One-time setup:** `docker node update --label-add ai-studio-data=true <node>` |
-| Migrations run post-deploy as a one-shot `docker run` on the stack network (with retries)         | Swarm ignores compose `depends_on` conditions                                                                                        |
-| `internal` network is `attachable: true`                                                          | Lets the migrate container join the overlay                                                                                          |
-| Services carry short DNS aliases (`backend`, `app-db`, `temporal`, …)                             | The web image's nginx proxies to `http://backend:3001`; aliases keep the images and env defaults identical between compose and Swarm |
-| Gatekeeper is conditional (`AUTH_ENABLED`)                                                        | The WB-229 public demo is deliberately login-free; internal instances can keep SSO                                                   |
+| Deviation                                                                                              | Reason                                                                                                                               |
+| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| Postgres ×2 + Temporal services with named volumes, pinned via `node.labels.ai-studio-data==true`      | AI Studio is stateful; Swarm volumes are node-local. **One-time setup:** `docker node update --label-add ai-studio-data=true <node>` |
+| No migration step — the backend applies Drizzle migrations at boot and restarts until Postgres answers | Swarm ignores compose `depends_on` conditions, so ordering must not rely on them                                                     |
+| Services carry short DNS aliases (`backend`, `app-db`, `temporal`, …)                                  | The web image's nginx proxies to `http://backend:3001`; aliases keep the images and env defaults identical between compose and Swarm |
+| Gatekeeper is conditional (`AUTH_ENABLED`)                                                             | The WB-229 public demo is deliberately login-free; internal instances can keep SSO                                                   |
 
 SSE note: Traefik streams responses by default, so the live execution stream
 works without special ingress config; the 15 s backend heartbeat keeps the

tools/deployment/ansible/deploy-application/main.yml

@@ -1,16 +1,15 @@
 ---
 # Deploys the AI Studio execution stack to the Docker Swarm cluster,
 # following the workflow-builder repo's deploy-application playbook. The
-# images are the same three targets the local compose builds
-# (deploy/ai-studio/Dockerfile); only the orchestration differs.
+# images are the same two targets the local compose builds
+# (deploy/ai-studio/Dockerfile); only the orchestration differs. Database
+# migrations run inside the backend at boot, so there is no migration step
+# here — the backend restarts until Postgres answers, then migrates itself.
 #
 # Differences from the workflow-builder playbook, all forced by AI Studio
 # being stateful:
 #   - Postgres x2 + Temporal services with named volumes, pinned to the node
 #     labeled `ai-studio-data=true` (Swarm volumes are node-local).
-#   - Migrations run as a one-shot container after stack deploy — Swarm
-#     ignores compose depends_on conditions, so ordering lives here.
-#   - The `internal` network is attachable so the migrate container can join.
 #   - Services get short DNS aliases (backend, app-db, temporal, ...) so the
 #     same images and env defaults work under compose and Swarm.
 #   - Gatekeeper is optional (AUTH_ENABLED=true): the WB-229 public demo is
@@ -203,8 +202,6 @@
 
           networks:
             internal:
-              # attachable so the one-shot migrate container below can join
-              attachable: true
             traefik-host-external:
               external: true
 
@@ -224,18 +221,3 @@
         with_registry_auth: yes
         compose:
           - '/mnt/docker-swarm-storage/stacks/{{ stack_name }}/{{ app_name }}.stack.yml'
-
-    # Swarm has no depends_on / one-shot service semantics: run Drizzle
-    # migrations as a plain container on the stack's attachable overlay
-    # network. Retries cover app-db still starting up on first deploy.
-    - name: Run database migrations
-      command: >
-        docker run --rm
-        --network {{ stack_name }}_internal
-        -e DATABASE_URL={{ database_url }}
-        {{ registry }}/{{ app_name }}:migrate-{{ image_tag }}
-        pnpm --filter backend db:migrate
-      register: migrate_result
-      retries: 10
-      delay: 6
-      until: migrate_result.rc == 0

tools/deployment/scripts/build-docker.sh

@@ -1,6 +1,6 @@
 #!/bin/sh
 # Build + push the AI Studio images to ACR, mirroring the workflow-builder
-# repo's tools/deployment/scripts/build-docker.sh. All three images come from
+# repo's tools/deployment/scripts/build-docker.sh. Both images come from
 # the same multi-target Dockerfile in deploy/ai-studio/ — this script only
 # adds registry tagging; the images are identical to the local-compose ones.
 #
@@ -15,7 +15,7 @@ COMMIT="${BITBUCKET_COMMIT:-$(git rev-parse HEAD)}"
 ENVIRONMENT="${BITBUCKET_DEPLOYMENT_ENVIRONMENT:-${DEPLOY_ENV:-}}"
 export IMAGE_TAG="${TAG_PREFIX:-}$COMMIT"
 
-for TARGET in runtime migrate web; do
+for TARGET in runtime web; do
   TAG="$REGISTRY/$APP_NAME:$TARGET-$IMAGE_TAG"
   docker build \
     -f ./deploy/ai-studio/Dockerfile \
@@ -30,7 +30,7 @@ if echo "$ALLOWED_ENVIRONMENTS" | grep -w "$ENVIRONMENT" > /dev/null; then
   # setup-az.sh exists in the deployment CI image; logging in by other means
   # (az acr login / docker login) is fine when running elsewhere
   [ -f /var/setup-az.sh ] && . /var/setup-az.sh
-  for TARGET in runtime migrate web; do
+  for TARGET in runtime web; do
     docker push "$REGISTRY/$APP_NAME:$TARGET-$IMAGE_TAG"
   done
 else

tools/deployment/swarm-alignment.decision-log.md

@@ -36,12 +36,12 @@ a static frontend:
 
 1. Database/Temporal services with named volumes pinned to a labeled node
    (`node.labels.ai-studio-data==true`) — Swarm volumes are node-local.
-2. Migrations as a post-deploy one-shot `docker run` with retries — Swarm
-   ignores compose `depends_on` conditions, so the ordering that compose
-   expressed declaratively lives in the playbook.
-3. An `attachable` internal network plus short DNS aliases (`backend`,
-   `app-db`, `temporal`) so the unmodified web image's nginx upstream and
-   the compose env defaults resolve identically under Swarm.
+2. No migration step (revised 11.06.2026) — the backend applies Drizzle
+   migrations at boot and restarts until Postgres answers, which sidesteps
+   Swarm's lack of `depends_on` ordering entirely.
+3. Short DNS aliases (`backend`, `app-db`, `temporal`) so the unmodified
+   web image's nginx upstream and the compose env defaults resolve
+   identically under Swarm.
 4. Gatekeeper made conditional (`AUTH_ENABLED`, default off) — the public
    demo is login-free by design; internal stage/dev instances can keep SSO.
 
@@ -79,6 +79,12 @@ a static frontend:
   - Secrets land in a stack file on the Swarm master's disk (inherited
     trade-off from the existing flow).
 
+## Revisions
+
+- **11.06.2026** — playbook migration task and the `attachable` network
+  removed; the backend migrates itself at boot. Image set is down to
+  `runtime` + `web`.
+
 ## Status
 
 Proposed — pending the DevOps conversation