fix(infra): build claude-runner via compose build-only service (#40)

* fix(infra): build claude-runner image out-of-band instead of via compose profile

The `claude-runner` image is a runtime dependency (the API spawns containers
from it per session), not a Compose service. A previous attempt shipped it as
a `profiles: [build-only]` service, but Compose excludes profiled services
from both build and run unless the profile is explicitly activated — which
Coolify does not do, causing `404 No such image: claude-runner:latest` when
the API tries to start a session.

Changes:
- Remove `claude-runner` service from infra/coolify/docker-compose.prod.yml
- Fix the Makefile `build-runner` tag (`claude-runner:latest`, no namespace)
- Make `make build` also build the runner
- Document the per-host one-time build in Quick Start, self-hosting guide,
  and Coolify guide (with pre-deployment command)
- Update CLAUDE.md decisions and troubleshooting

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* refactor(infra): use build-only service pattern for claude-runner

Switches from "out-of-band make build-runner" (previous commit) to a proper
Compose build-only service:

    claude-runner:
      build: { context: ./infra/docker/claude-runner }
      image: claude-runner:latest
      entrypoint: ["/bin/true"]
      restart: "no"

The container exits immediately on `docker compose up` (entrypoint is
overridden to `/bin/true`) and is not restarted, so it produces no runtime
overhead — but Compose still builds the image and leaves it tagged
`claude-runner:latest` on the host, ready for the API to spawn session
containers from via the Docker socket.

Benefits over the previous commit:
- `docker compose up --build` is the single command on every host (Coolify,
  VPS, local dev, ECS EC2)
- No Coolify pre-deployment command to configure in the UI
- No `make build-runner` step for users
- Rebuilds automatically whenever `infra/docker/claude-runner/` changes

Applied to both the dev `docker-compose.yml` and the prod
`infra/coolify/docker-compose.prod.yml`. `make build-runner` stays as a
convenience shortcut for quick iteration. Docs reverted to the simpler
"just run compose" narrative.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mariuspruvot

CLAUDE.md

@@ -137,7 +137,7 @@ Key additions for production: `ENVIRONMENT=production`, `ADMIN_PASSWORD`, `CORS_
 - **Open source target**: designed for self-hosting with own Claude licenses
 - **Post-results to PR**: after session completion, the API can post score card as a PR comment — opt-in per installation via `post_results_to_pr` boolean; extraction and formatting in `container/pr_comment.py`, triggered in `_event_stream()` after `mark_completed()`
 - **Coolify deployment**: Two-domain setup via Traefik: `helprs.tech` (web) and `api.helprs.tech` (API). TLS via Let's Encrypt, managed by Coolify. Domains are set in Coolify UI (General > Domains for api / Domains for web) — they may get cleared on redeploy, re-check after each deploy. "Preserve Repository During Deployment" must be enabled so skills are available on the host. The prod compose uses `./` paths (repo-root-relative) because Coolify sets `--project-directory` to the repo root.
-- **claude-runner image**: built via a `profiles: [build-only]` service in the prod compose — Coolify builds the image but never starts the container. The API spawns it dynamically. Image name is `claude-runner:latest` (no namespace prefix).
+- **claude-runner image**: declared in both `docker-compose.yml` and `infra/coolify/docker-compose.prod.yml` as a **build-only service** — `entrypoint: ["/bin/true"]` + `restart: "no"` so the container exits immediately on `up`, leaving only the built image `claude-runner:latest` on the host. The API spawns containers from this image dynamically via the mounted Docker socket. Image tag is hard-coded in `container/service.py:CLAUDE_RUNNER_IMAGE` — it must stay `claude-runner:latest` (no namespace prefix). Earlier attempt with `profiles: [build-only]` was reverted: `profiles:` excludes a service from both build AND run unless the profile is explicitly activated, which Coolify does not do, causing `404 No such image` failures on session spawn.
 - **Non-root API container**: production Dockerfile uses `appuser` with `chown -R appuser:appuser /app` for uv cache writes. Docker socket access requires `group_add: ["${DOCKER_GID:-994}"]` in the compose to match the host's docker group GID.
 - **BYOK supports OAuth tokens**: `validate_claude_key()` accepts both API keys (`sk-ant-api03-...`) and OAuth tokens (`sk-ant-oat...`). OAuth tokens skip server-side validation (validated at runtime by Claude Code CLI). Frontend setup page guides users to `claude setup-token`.
 - **VITE_* build args**: `VITE_API_URL` and `VITE_GITHUB_APP_SLUG` are build-time variables — must be passed as `args` in the compose and declared as `ARG`/`ENV` in `Dockerfile.web`. They cannot be set at runtime.

Makefile

@@ -19,8 +19,14 @@ test:
 build:
 	docker compose -f infra/coolify/docker-compose.prod.yml build
 
+# Rebuild just the claude-runner image. Normally you don't need to call this
+# directly — both compose files declare claude-runner as a build-only service,
+# so `docker compose up --build` produces the image as a side-effect. This
+# shortcut is useful for quick iteration on infra/docker/claude-runner/ without
+# touching the API or web services. Image tag must match
+# CLAUDE_RUNNER_IMAGE in helprs/modules/container/service.py.
 build-runner:
-	docker build -t helprs/claude-runner:latest infra/docker/claude-runner/
+	docker build -t claude-runner:latest infra/docker/claude-runner/
 
 migrate:
 	cd apps/api && uv run alembic upgrade head

README.md

@@ -42,8 +42,7 @@ cd helprs
 cp .env.example .env
 # Fill in .env (see docs/self-hosting.md for details)
 
-docker compose up --build        # API :8000, Web :5173, Postgres :5432
-make build-runner                # Build the Claude Code container image
+docker compose up --build        # API :8000, Web :5173, Postgres :5432 (+ builds the claude-runner image)
 ```
 
 Open [http://localhost:5173](http://localhost:5173), authenticate with GitHub, and you're ready to go.

docker-compose.yml

@@ -34,6 +34,16 @@ services:
       - CHOKIDAR_USEPOLLING=true
     command: npx vite --host 0.0.0.0 --port 5173
 
+  # Build-only service: the API spawns containers from this image dynamically
+  # via the Docker socket. `entrypoint: /bin/true` + `restart: "no"` make the
+  # container exit immediately — the image stays available on the host.
+  claude-runner:
+    build:
+      context: ./infra/docker/claude-runner
+    image: claude-runner:latest
+    entrypoint: ["/bin/true"]
+    restart: "no"
+
   db:
     image: postgres:16-alpine
     ports:

docs/deploy-coolify.md

@@ -144,8 +144,8 @@ Click **Save**. Coolify generates Traefik routing rules and provisions Let's Enc
 Click **Deploy**. Coolify will:
 
 1. Clone the repo
-2. Build the API, Web, and claude-runner images
-3. Start the API, Web, and DB containers (claude-runner is `profiles: [build-only]`, not started)
+2. Build the API, Web, and claude-runner images (claude-runner is a **build-only service** — the container exits immediately with `/bin/true`, leaving the image available on the host for the API to spawn session containers from)
+3. Start the API, Web, and DB containers
 4. Run Alembic migrations automatically (API entrypoint runs `alembic upgrade head`)
 
 ### Verify
@@ -219,20 +219,13 @@ The `docker-compose.prod.yml` has `group_add: ["${DOCKER_GID:-994}"]`. If your s
 docker images | grep claude-runner
 # Should show: claude-runner   latest   <id>   <date>   <size>
 
-docker ps | grep claude-runner
-# Should be empty (it's only spawned on demand, not a long-lived service)
+docker ps -a | grep claude-runner
+# Expected: an "Exited (0)" container from the last compose up — this is
+# normal, the service is declared as build-only (entrypoint /bin/true).
+# The API does NOT use this container — it spawns fresh ones per session.
 ```
 
-If the image is missing, the `claude-runner` service may have been excluded from the build. Verify the compose file includes:
-
-```yaml
-claude-runner:
-  build:
-    context: ./infra/docker/claude-runner
-  image: claude-runner
-  profiles:
-    - build-only
-```
+If the image is missing, the compose build step failed. Check Coolify's **Logs** tab for build errors (usually a Dockerfile issue in `infra/docker/claude-runner/`) and redeploy.
 
 ---
 
@@ -295,7 +288,20 @@ The `DOCKER_GID` does not match your server's Docker group. See [step 8](#8-dock
 No such image: claude-runner:latest
 ```
 
-Verify the compose includes the claude-runner service with `profiles: [build-only]`. Redeploy to rebuild the image.
+The claude-runner service did not build. Verify `infra/coolify/docker-compose.prod.yml` includes the service block:
+
+```yaml
+claude-runner:
+  build:
+    context: ./infra/docker/claude-runner
+  image: claude-runner:latest
+  entrypoint: ["/bin/true"]
+  restart: "no"
+```
+
+Redeploy via Coolify. Check the deploy logs for errors in the `claude-runner` build step. The image name must be exactly `claude-runner:latest` (no namespace prefix) — the API references this tag in `apps/api/src/helprs/modules/container/service.py`.
+
+If the image was pruned manually (`docker image prune -a`), just redeploy — Compose rebuilds it as part of the stack.
 
 ### Skills directory is empty
 

docs/self-hosting.md

@@ -169,17 +169,24 @@ POSTGRES_PASSWORD=    # Strong password for production DB
 ### Option A: Docker Compose (simplest)
 
 ```bash
-# Build and start all services (including claude-runner image)
+# Build and start all services. The claude-runner image is built as a side-
+# effect and left available on the host for the API to spawn containers from.
 docker compose -f infra/coolify/docker-compose.prod.yml up -d --build
 
 # Verify services are healthy
 docker compose -f infra/coolify/docker-compose.prod.yml ps
 ```
 
-!!! note "claude-runner image"
-    The `claude-runner` service in the compose file uses `profiles: [build-only]`.
-    It is built during `docker compose up --build` but does not run as a long-lived
-    service. The API spawns claude-runner containers on demand.
+!!! note "About the `claude-runner` "Exited" container"
+    The `claude-runner` service is a **build-only service**: `docker compose up`
+    builds the image, starts the container, which exits immediately (its entrypoint
+    is overridden to `/bin/true`) with `restart: "no"`. The container stays in
+    `Exited (0)` state and is not restarted — but the image `claude-runner:latest`
+    remains available on the host. The API spawns new containers from this image
+    per session via the Docker socket.
+
+    This pattern keeps `docker compose up --build` as the single source of truth
+    for the whole stack, including the runner image.
 
 The API runs on port 8000, the frontend on port 80. You need a reverse proxy (nginx, Caddy, Traefik) in front to handle TLS and route traffic.
 
@@ -211,7 +218,7 @@ cd helprs
 cp .env.example .env
 # Edit .env with your values...
 
-# Start services
+# Start services (the claude-runner image is built as a build-only service)
 docker compose -f infra/coolify/docker-compose.prod.yml up -d --build
 
 # Set up your preferred reverse proxy (Caddy example)
@@ -318,7 +325,7 @@ If you enabled **Post results to PR** in installation settings, the score card i
 ### Container won't start
 
 - Verify Docker socket is mounted: check that `/var/run/docker.sock` is accessible to the API container
-- Verify the claude-runner image exists: `docker images | grep claude-runner`
+- Verify the claude-runner image exists: `docker images | grep claude-runner` — if missing, run `docker compose up --build` (the image is built as part of the normal compose up)
 - Check `SKILLS_HOST_PATH` is an absolute path and the directory exists on the Docker host
 - Verify the `DOCKER_GID` matches the host's Docker group: `getent group docker | cut -d: -f3`
 - Check API logs for container creation errors: `docker compose logs api | grep container`

infra/coolify/docker-compose.prod.yml

@@ -60,12 +60,18 @@ services:
           memory: 128M
     restart: unless-stopped
 
+  # Build-only service: the API spawns containers from this image dynamically
+  # via the Docker socket. We still declare it here so `docker compose up --build`
+  # produces the image; `entrypoint: /bin/true` + `restart: "no"` make the
+  # container exit immediately without becoming a long-lived service. The image
+  # `claude-runner:latest` then stays available on the host for the API to use.
+  # Image tag is hard-coded in helprs/modules/container/service.py.
   claude-runner:
     build:
       context: ./infra/docker/claude-runner
-    image: claude-runner
-    profiles:
-      - build-only
+    image: claude-runner:latest
+    entrypoint: ["/bin/true"]
+    restart: "no"
 
   db:
     image: postgres:16-alpine