Playa/docs/superpowers/specs/2026-09-26-docker-deployment-design.md

# Docker deployment (Coolify) — design

Date: 2026-09-26. Status: draft.
Depends on: `2026-09-26-process-environment-hook-design.md` (the secrets below stay out of agent-spawned processes),
`2026-09-26-scheduler-design.md` §7 (the default time zone).

## Goal

Run the Telegram host (`hosts/Volcanic.AgenticCore.Telegram`) as a single container on Coolify, deployed from
this repo's `docker-compose.yml`. The container carries everything the agent's `bash` tool and the Claude Code
provider need, runs as a non-root user, and keeps workspaces, sessions and the Claude login across redeploys.
`docker compose up -d --build` on any Docker host runs the same thing locally.

Reference: VolcanicSecretary (`Dockerfile`, `docker-compose.yml`, `docker-entrypoint.sh`), adapted to a .NET
build and to the Claude Code provider's subscription-only rules.

## Decisions

| Topic | Decision |
|---|---|
| Files | `Dockerfile`, `.dockerignore`, `docker-compose.yml`, `.env.example` at the repo root; user doc `docs/docker.md` |
| Build | Multi-stage: `mcr.microsoft.com/dotnet/sdk:10.0-noble` → `mcr.microsoft.com/dotnet/runtime:10.0-noble` |
| Publish | Framework-dependent `dotnet publish -c Release` of the Telegram host only. No self-contained, no AOT, no single-file: `claude` launches the bridge as `dotnet <Bridge>.dll`, so the `dotnet` muxer and a loose `Bridge.dll` + `.runtimeconfig.json` must exist |
| Entry | `ENTRYPOINT ["setpriv", "--reuid=1654", "--regid=1654", "--init-groups", "--inh-caps=-all", "--", "dotnet", "Volcanic.AgenticCore.Telegram.dll"]`: `setpriv` (util-linux, already in the base image) drops to `app` and execs `dotnet`, so `Environment.ProcessPath` is still the muxer `BridgeLocator.FindDotnet` wants. No entrypoint script |
| Agent tools | `bash`, `git`, `ripgrep`, `python3` (+ `python-is-python3`, `python3-venv`), `curl`, `ca-certificates`, `tzdata`, `jq`, `less`, `procps`, `openssh-client` |
| Node | Node.js 24 from NodeSource (`ARG NODE_MAJOR=24`); Ubuntu noble's `nodejs` is too old |
| Claude CLI | `npm install -g @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}`, `ARG CLAUDE_CODE_VERSION=2.1` (newest 2.1.x at build time; set an exact version to pin). Updated by rebuilding, never in place |
| Playwright | `ARG INSTALL_PLAYWRIGHT=false` in the Dockerfile; compose passes `true`. Installs `@playwright/mcp` globally at the version pinned by the MCP spec, and Chromium + OS deps under `/opt/ms-playwright`. Compose points the preset at the preinstalled `playwright-mcp` (no npx download) and adds `--no-sandbox` |
| User | The image's default user stays root so that PID 1 (compose's `init: true`, i.e. `docker-init`) is root-owned; the bot and everything it spawns run as the base image's non-root `app` user (1654, `$APP_UID`), `HOME=/home/app`. With `USER app`, `docker-init` runs as `app` and its `/proc/1/environ` (the whole container environment, secrets included) is readable by the agent's `bash` (checked on Docker 29) |
| Data | Three named volumes under `/data`: `workspaces`, `agent`, `claude` |
| Config | Environment only, set in Coolify. Required: `TELEGRAM_BOT_TOKEN`, `TELEGRAM_ALLOWED_USER_IDS`. Optional: `OPENAI_API_KEY`, `STT_MODEL`, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `DEFAULT_TIMEZONE`, `PROCESS_ENV_ALLOW`, `TZ`, `PLAYWRIGHT_ENABLED`, `PLAYWRIGHT_HEADLESS`, `PLAYWRIGHT_BROWSER`, `PLAYWRIGHT_EXTRA_ARGS`, `PLAYWRIGHT_COMMAND` |
| Healthcheck | None (see below) |
| Coolify | No `ports`, no `expose`, no domain, no `SERVICE_FQDN_*`; `restart: unless-stopped`; `init: true` |
| Local script | None. `cp .env.example .env && docker compose up -d --build` is the local run; the `dotnet run` path in `docs/telegram-bot.md` stays for development |

Out of scope: webhooks/HTTP endpoints, a .NET SDK inside the runtime image for the agent to use, CI image publishing
to a registry, multi-arch builds (the image is built on the Coolify server, whatever its arch), running tests in
the image build.

## Dockerfile

Build stage (`sdk:10.0-noble`):

1. `WORKDIR /src`. Copy `Directory.Build.props`, `VolcanicAgenticCore.slnx` and only the `*.csproj` files the host
   needs (Abstractions, core, ClaudeCode, ClaudeCode.Bridge, GoogleCalendar, Mcp, Scheduler, Telegram), then
   `dotnet restore hosts/Volcanic.AgenticCore.Telegram` — a cached layer until a project file changes.
2. Copy `src/`, `extensions/`, `hosts/` and `dotnet publish hosts/Volcanic.AgenticCore.Telegram -c Release
   --no-restore -o /out`. `TreatWarningsAsErrors` applies, so a warning fails the image build as it fails `dotnet build`.
3. Guard: `test -f /out/Volcanic.AgenticCore.Extensions.ClaudeCode.Bridge.dll && test -f
   /out/Volcanic.AgenticCore.Extensions.ClaudeCode.Bridge.runtimeconfig.json`. The bridge reaches the output through
   a `ReferenceOutputAssembly="false"` project reference; if `publish` drops the runtimeconfig (it does not in
   `build`), fix the csproj, not the Dockerfile.

Runtime stage (`runtime:10.0-noble`), as root:

1. `apt-get install --no-install-recommends` the agent tools above, then NodeSource `nodejs`; clean apt lists.
2. `npm install -g @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION} && claude --version` (fails the build if the
   CLI does not run). The global prefix `/usr/lib/node_modules` stays root-owned, so the CLI's auto-updater cannot
   replace the binary at runtime: a Claude Code upgrade changes what `system/init` validation sees and invalidates
   the prompt cache, so it should only arrive with a rebuild.
3. If `INSTALL_PLAYWRIGHT=true`: `ENV PLAYWRIGHT_BROWSERS_PATH=/opt/ms-playwright`,
   `npm install -g @playwright/mcp@${PLAYWRIGHT_MCP_VERSION}`, then run the
   `playwright` CLI **from that package's own dependency** with `install --with-deps chromium`, so browser build and
   library version match. `chmod -R a+rX /opt/ms-playwright`. Roughly +400 MB. `PLAYWRIGHT_BROWSERS_PATH` is set
   unconditionally so the MCP spec (`2026-09-26-mcp-client-playwright-design.md`) can rely on it: its server
   process inherits the environment. `ARG PLAYWRIGHT_MCP_VERSION` defaults to the exact version in the MCP spec's
   `PlaywrightPreset.DefaultPackage`, which is the single source of truth. A unit test in that spec fails when the two
   differ, so bumping the version means changing both in one commit. Compose does not override this arg.
4. `mkdir -p /data/workspaces /data/agent /data/claude /home/app && chown -R app:app /data /home/app`. Named volumes
   copy this ownership on first mount, which is what lets a non-root process write to them.
5. `COPY --from=build /out /app`, `WORKDIR /app`. No `USER` (see the User row); an earlier step checks that `app` is
   uid/gid 1654, which the entrypoint hard-codes.
6. Environment baked into the image (compose and Coolify may override):

| Variable | Value | Why |
|---|---|---|
| `Telegram__WorkspaceRoot` | `/data/workspaces` | Chat `<id>` works in `/data/workspaces/<id>` |
| `VOLCANIC_AGENT_DIR` | `/data/agent` | Sessions, `extensions/*.dll`, `settings.json`, `auth.json` |
| `HOME` | `/home/app` | The image user is root, so Docker would otherwise set `/root` |
| `CLAUDE_CONFIG_DIR` | `/data/claude` | Moves both `~/.claude/` and `~/.claude.json` (credentials and onboarding state) into one volume. Already on the provider's env allow-list, so every `claude` child and `claude auth login` see it |
| `DOTNET_CLI_TELEMETRY_OPTOUT`, `DOTNET_NOLOGO` | `1` | Quiet |
| `TZ` | `UTC` | Overridable |
| `DOTNET_EnableDiagnostics` | `0` | Turns off the runtime's diagnostic IPC socket, which would hand the bot's environment to the agent's same-uid processes and bypass the host's non-dumpable hardening (process-environment-hook spec §8). Unset it (with `ProcessEnvironment__HardenHostProcess=false`) only to attach `dotnet-dump`/`dotnet-trace` while debugging |

`VOLUME` is not declared in the Dockerfile; the compose file owns volumes (Coolify treats anonymous volumes badly).

## docker-compose.yml

```yaml
services:
  bot:
    build:
      context: .
      args:
        INSTALL_PLAYWRIGHT: ${INSTALL_PLAYWRIGHT:-true}
        CLAUDE_CODE_VERSION: ${CLAUDE_CODE_VERSION:-2.1}
    restart: unless-stopped
    # dotnet does not reap orphans; killed `claude` trees and bash tool children would pile up as zombies.
    init: true
    # Chromium crashes with Docker's 64 MB /dev/shm.
    shm_size: 1gb
    stop_grace_period: 30s
    environment:
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
      - TELEGRAM_ALLOWED_USER_IDS=${TELEGRAM_ALLOWED_USER_IDS}
      - Telegram__Model=${TELEGRAM_MODEL:-claude-code/claude-opus-5-5}
      - TZ=${TZ:-UTC}
      - Logging__LogLevel__Default=${LOG_LEVEL:-Information}
      # Optional features; empty means off / default.
      - OPENAI_API_KEY=${OPENAI_API_KEY:-}                  # speech to text (attachments spec)
      - STT_MODEL=${STT_MODEL:-}
      - GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID:-}              # Google Calendar (calendar spec)
      - GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET:-}
      - DEFAULT_TIMEZONE=${DEFAULT_TIMEZONE:-}              # chats' default zone (scheduler spec §7); empty → TZ
      - PROCESS_ENV_ALLOW=${PROCESS_ENV_ALLOW:-}            # deny-listed variables the agent may see, e.g. GH_TOKEN
      # Playwright MCP preset (MCP spec). Enabled when the image has it; the preinstalled binary, no npx download.
      - PLAYWRIGHT_ENABLED=${PLAYWRIGHT_ENABLED:-${INSTALL_PLAYWRIGHT:-true}}
      - PLAYWRIGHT_HEADLESS=${PLAYWRIGHT_HEADLESS:-true}     # no display in the container
      - PLAYWRIGHT_BROWSER=${PLAYWRIGHT_BROWSER:-}
      - PLAYWRIGHT_EXTRA_ARGS=${PLAYWRIGHT_EXTRA_ARGS:---no-sandbox}
      - PLAYWRIGHT_COMMAND=${PLAYWRIGHT_COMMAND:-playwright-mcp}
    volumes:
      - workspaces:/data/workspaces
      - agent:/data/agent
      - claude:/data/claude

volumes:
  workspaces:
  agent:
  claude:
```

- No `ports`/`expose`: long polling only makes outbound connections. No domain is configured in Coolify, so no
  Traefik labels are generated.
- **No `ANTHROPIC_*`, `CLAUDE_CODE_OAUTH_TOKEN`, `CLAUDE_CODE_USE_*` entries**, ever: the provider refuses to run
  with them. `docs/docker.md` says so next to the Coolify env setup, because shared/team variables in Coolify
  are the likely way one sneaks in.
- Env mapping: the two required settings use the existing shortcuts (`TELEGRAM_BOT_TOKEN`,
  `TELEGRAM_ALLOWED_USER_IDS`, comma separated) because a list in `Telegram__AllowedUserIds__0..n` form is awkward
  in Coolify. Everything else in `TelegramOptions` is reachable as `Telegram__<Name>` (e.g.
  `Telegram__ReconnectMaxDelay=00:02:00`) without a compose change, by adding it in Coolify and to `environment`.
  The Claude provider's `VOLCANIC_CLAUDE_CODE_IDLE_TIMEOUT_MS` / `..._TOTAL_TIMEOUT_MS` work the same way, as do
  the `Scheduler__*`, `GoogleCalendar__*`, `ProcessEnvironment__*` and `Telegram__Speech__*` /
  `Telegram__InputDebounce` settings of the sibling specs.
- Optional features use the env shortcuts their specs define: `OPENAI_API_KEY` (+ `STT_MODEL`) turns on speech to
  text; `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET` turn on the calendar, and each chat then connects its own Google
  account. Empty values mean off, so they're in `environment` and `.env.example` from the start. `OPENAI_API_KEY` is
  not on the Claude Code provider's denied list and never reaches `claude`.
- Time zones: each chat has its own (`/timezone`). A chat that never set one uses `DEFAULT_TIMEZONE`, else the
  container's `TZ` (default `UTC`), so a deployment whose users are mostly in one zone should set `DEFAULT_TIMEZONE`.
  The chat's zone is also passed as `TZ` to the agent's `bash` and watcher scripts (the image has `tzdata`). Calendar
  times use the calendar's own zone, else the chat's.
- Secrets set here (`TELEGRAM_BOT_TOKEN`, `OPENAI_API_KEY`, `GOOGLE_CLIENT_SECRET` and anything matching
  `*_API_KEY`, `*_TOKEN`, `*_SECRET`, `*_PASSWORD` or their `Section__Key` forms) are removed from the environment of
  the agent's `bash`, scheduled scripts and MCP servers by the process environment hook. To give the agent a
  credential on purpose (say `GH_TOKEN` for `gh`), add it in Coolify and list its name in `PROCESS_ENV_ALLOW`; an MCP
  server gets one through its own `env` entry instead. On top of that, the bot (the only child of the root-owned
  PID 1) makes itself non-dumpable at startup, so the agent can't read its `/proc/<pid>/environ` or attach to it,
  PID 1's own `/proc/1/environ` is root-only, and the configured secrets' values are replaced by `[REDACTED]` in
  tool output (process-environment-hook spec §8–§9). The side effect is no core dumps and no
  `dotnet-dump`/`dotnet-trace` attach; `ProcessEnvironment__HardenHostProcess=false` turns it off for a debugging
  session. The container stays the real isolation boundary: none of this is a sandbox.
- Playwright: `PLAYWRIGHT_COMMAND=playwright-mcp` runs the globally installed, version-pinned server, so the first
  browser call in a chat doesn't wait on an npx download. `PLAYWRIGHT_EXTRA_ARGS` defaults to `--no-sandbox`:
  Chromium's sandbox needs user namespaces, which Docker's default seccomp profile denies to the non-root `app` user,
  so the container is the isolation boundary. Overriding `PLAYWRIGHT_EXTRA_ARGS` must keep `--no-sandbox`.
  `PLAYWRIGHT_ENABLED` follows `INSTALL_PLAYWRIGHT` (nested default, supported by Compose v2), so an image built
  without Playwright doesn't advertise tools it can't run.
- The owner (first id in `TELEGRAM_ALLOWED_USER_IDS`) gets the `🟢 Online.` message and the Claude Code re-login
  prompts. The calendar has no owner special case: every chat connects its own account.
- Coolify prefixes named volumes with the resource uuid; they survive redeploys and are only removed when the
  resource is deleted with its volumes. Bind mounts (as in VolcanicSecretary) also work but the host directories
  must then be owned by uid 1654; the doc mentions this in one line.
- Deploys: Coolify stops the old container before starting the new one for compose resources. If they ever overlap,
  the second poller gets `409 Conflict`, which the polling service already backs off from.

## Healthcheck

None. The bot serves no HTTP, and the failure modes a probe could detect are already handled in-process: lost
connectivity self-heals with backoff (`ReconnectPolicy`), a dead polling loop is restarted, and the unrecoverable
cases exit the process (`401` → exit 1, invalid config → exit 2), which `restart: unless-stopped` turns into a
visible restart loop in Coolify's logs. A file-heartbeat probe would add a moving part for no new signal. Coolify
shows the service as running without health status; that is acceptable.

## First run and Claude login

1. In Coolify: new resource from this repo, build pack *Docker Compose*, set `TELEGRAM_BOT_TOKEN` and
   `TELEGRAM_ALLOWED_USER_IDS` (owner first), deploy.
2. The start log says Claude Code was found (image-provided) and lists allowed users.
3. The owner opens the bot, sends `/start`, then `/claude-code-login`: link + code prompt arrive as one message, the
   pasted code is fed to `claude auth login --claudeai` inside the container, and credentials land in
   `/data/claude`. `/claude-code-doctor` should then report logged in, `claude.ai`, bridge ok.
4. Later expiries use the existing owner re-login flow; nothing Docker-specific.

Fallback without the bot: `docker exec -u app -it <container> claude auth login --claudeai` (same `CLAUDE_CONFIG_DIR`;
`docker exec` defaults to root, whose credentials the bot couldn't read). Copying an existing `.credentials.json` into
the `claude` volume also works but is not the documented path.

## Extensions and project context

- Extra extension assemblies go to `/data/agent/extensions/*.dll` (user directory) or
  `/data/workspaces/<chatId>/.volcanic/extensions/` (project directory); discovery is unchanged. Getting a DLL there
  is `docker cp` + restart; they must be built against the same `Volcanic.AgenticCore.Abstractions` version as the image.
- `AGENTS.md` / `CLAUDE.md`, `PERSONA.md`, `MEMORY.md` live in each chat's workspace directory in the `workspaces`
  volume, edited by the agent or by `docker exec`.

## Docs

- New `docs/docker.md`: build args, env table (with which variables the agent can't see, and `PROCESS_ENV_ALLOW`), volumes, Coolify steps, first login, no-API-key warning, updating
  Claude Code (redeploy; set `CLAUDE_CODE_VERSION` to pin), troubleshooting (`[executable_missing]`, `[auth]`,
  `[mcp_startup]` → bridge files, permission denied on bind mounts → chown 1654, `409` → another instance).
- `README.md`: one line under the Telegram quick start linking `docs/docker.md`.
- `docs/telegram-bot.md`: "Security" points at the container as the recommended way to run it.
- Update the "Out of scope: … Docker/Coolify" line in `2026-09-25-telegram-host-design.md` to reference this spec.

## Verification

No unit tests (nothing in C# changes). Manual checklist in the implementation plan:

1. `docker compose build` succeeds with `INSTALL_PLAYWRIGHT=false` and `true`; the bridge guard and `claude --version` pass.
2. `docker compose up` with a real bot: allowed user gets answers; `/claude-code-login` then `/claude-code-doctor`
   all green; `id` via the agent's bash reports uid 1654; `env` via the agent's bash shows neither
   `TELEGRAM_BOT_TOKEN` nor `OPENAI_API_KEY`, and `date` shows the chat's zone after `/timezone Europe/Berlin`;
   `cat /proc/1/environ` via the agent's bash fails with permission denied, and no `dotnet-diagnostic-*` socket
   exists under `/tmp`.
3. Agent can run `git`, `rg`, `python3`, `node`, `npx`; with Playwright, `playwright-mcp --version` prints the pinned version offline, and "Open https://example.com and tell me the H1" works in a chat on the first try (no npx download, no sandbox error).
4. `docker compose down && docker compose up -d --build`: previous chat resumes, no re-login needed, workspace files remain.
5. Setting `ANTHROPIC_API_KEY` in compose makes the provider refuse with its documented error (then remove it).

## Open questions

1. Persist `HOME` too? `~/.gitconfig`, `~/.ssh`, `gh` auth and the npm/npx cache are lost on redeploy with this
   design. A fourth volume at `/home/app` would keep them; left out until there is a need.
2. Playwright default: compose builds it in (`true`) on the assumption that the MCP spec ships; flip the compose
   default to `false` if that spec lands later. (Sandboxing and which binary is launched are settled above.)
3. `CLAUDE_CODE_VERSION=2.1` tracks the newest 2.1.x at build time. Pin an exact, doctor-verified version instead,
   at the cost of manual bumps?
4. Should the agent get a .NET SDK in the image (`INSTALL_DOTNET_SDK` build arg, +~700 MB) so it can build .NET
   projects in its workspace?