feat(compose): full-stack Caddy + docker-compose wiring

Brings up the whole platform behind a single Caddy entrypoint so the
routing topology can be exercised end-to-end before any feature code
lands. Same Caddyfile shape (admin / data plane / dashboard) maps to
single-process MVP today and will map to cluster mode later by
swapping the upstream lists, not by restructuring the proxy.

  * caddy/Caddyfile — dev: HTTP only, picloud and dashboard upstreams
    by service name. caddy/Caddyfile.prod — Let's Encrypt for
    PICLOUD_DOMAIN with PICLOUD_ADMIN_EMAIL.
  * docker/orchestrator.Dockerfile — multi-stage build of the
    `picloud` all-in-one against the pinned 1.92 toolchain; debian
    slim runtime, non-root user, /healthz HEALTHCHECK.
  * docker/dashboard.Dockerfile — node:24-alpine builder + caddy
    runtime that serves the static SPA with SPA fallback.
  * docker-compose.yml — postgres + picloud + dashboard + caddy,
    Caddy exposed on host :8000 (configurable), Postgres on :15432
    (loopback only). Health-gated startup ordering.
  * docker-compose.prod.yml — overlay: removes Postgres host
    mapping, expands Caddy to 80/443/443udp, swaps Caddyfile.prod,
    adds restart policy.
  * .env.example documents every knob the compose stack reads.

Verified via `docker compose up -d`:
  * `curl :8000/healthz` → 200 ok (orchestrator)
  * `curl :8000/api/admin/scripts` → 404 (manager, routed correctly)
  * `curl :8000/api/execute/<id>` → 404 (orchestrator, routed correctly)
  * `curl :8000/` → SPA index served (dashboard via Caddy)
  * `curl :8000/favicon.svg` → 200 image/svg+xml
  * Postgres healthy and reachable on 127.0.0.1:15432.

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

.env.example

@@ -0,0 +1,27 @@
+# Copy to `.env` and adjust. `docker compose up` reads this file
+# automatically; the picloud binary on the host ignores it (use the
+# explicit env vars listed in CLAUDE.md).
+
+# ---------- Caddy ----------
+# Host port the dev stack listens on. Default 8000 because :80 needs
+# privileges and :8080 is occupied by an unrelated local service on
+# this dev machine.
+PICLOUD_HOST_PORT=8000
+
+# Production only — used by docker-compose.prod.yml. Caddy obtains a
+# Let's Encrypt certificate for PICLOUD_DOMAIN using PICLOUD_ADMIN_EMAIL.
+# PICLOUD_DOMAIN=picloud.example.com
+# PICLOUD_ADMIN_EMAIL=admin@example.com
+
+# ---------- Postgres ----------
+POSTGRES_DB=picloud
+POSTGRES_USER=picloud
+POSTGRES_PASSWORD=picloud
+
+# Host port the dev Postgres listens on (loopback only). Default 15432
+# because the conventional 5432 is frequently already bound locally.
+PICLOUD_POSTGRES_HOST_PORT=15432
+
+# ---------- Orchestrator ----------
+# tracing-subscriber filter; comma-separated module=level pairs.
+RUST_LOG=info,picloud=debug

caddy/Caddyfile

@@ -0,0 +1,51 @@
+# PiCloud dev Caddyfile.
+#
+# Same routing shape as prod, with two differences:
+#   - bound to plain HTTP (no domain, no automatic TLS)
+#   - upstreams are the docker-compose service names
+#
+# Control plane (`/api/admin/*`) and data plane (`/api/execute/*`, `/exec/*`)
+# both terminate on the `picloud` all-in-one for now; in cluster mode the
+# data-plane handles will list multiple orchestrator upstreams here while
+# the admin handle still points at a single manager.
+{
+	auto_https off
+	admin off
+	log {
+		output stdout
+		format console
+	}
+}
+
+:80 {
+	# Health probes go straight to the orchestrator.
+	handle /healthz {
+		reverse_proxy picloud:8080
+	}
+
+	# Control plane → manager (single-process: picloud).
+	handle /api/admin/* {
+		reverse_proxy picloud:8080
+	}
+
+	# Data plane → orchestrator (single-process: picloud).
+	handle /api/execute/* {
+		reverse_proxy picloud:8080
+	}
+	handle /exec/* {
+		reverse_proxy picloud:8080
+	}
+
+	# Everything else → dashboard SPA (Caddy serves a self-contained
+	# dashboard container that already runs file_server with index.html
+	# fallback for client-side routing).
+	handle {
+		reverse_proxy dashboard:80
+	}
+
+	log {
+		output stdout
+		format console
+	}
+}
+}

caddy/Caddyfile.prod

@@ -0,0 +1,37 @@
+# PiCloud production Caddyfile.
+#
+# Set PICLOUD_DOMAIN and PICLOUD_ADMIN_EMAIL in the environment Caddy is
+# started from (docker-compose.prod.yml passes them through). Caddy then
+# obtains and renews a Let's Encrypt cert automatically for that domain.
+{
+	email {$PICLOUD_ADMIN_EMAIL}
+}
+
+{$PICLOUD_DOMAIN} {
+	encode zstd gzip
+
+	handle /healthz {
+		reverse_proxy picloud:8080
+	}
+
+	handle /api/admin/* {
+		reverse_proxy picloud:8080
+	}
+
+	handle /api/execute/* {
+		reverse_proxy picloud:8080
+	}
+	handle /exec/* {
+		reverse_proxy picloud:8080
+	}
+
+	handle {
+		reverse_proxy dashboard:80
+	}
+
+	log {
+		output stdout
+		format json
+	}
+}
+}

docker-compose.prod.yml

@@ -0,0 +1,39 @@
+# Production overlay. Apply on top of docker-compose.yml:
+#
+#   docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+#
+# Pre-flight checks:
+#   - PICLOUD_DOMAIN and PICLOUD_ADMIN_EMAIL must be set (Caddy uses them
+#     for automatic Let's Encrypt issuance).
+#   - POSTGRES_PASSWORD must be set to a real secret, not the dev default.
+
+services:
+  postgres:
+    # Pull the published port mapping; Postgres is reachable only inside
+    # the compose network in production.
+    ports: !reset []
+    restart: unless-stopped
+
+  picloud:
+    restart: unless-stopped
+    environment:
+      RUST_LOG: ${RUST_LOG:-info,picloud=info}
+
+  dashboard:
+    restart: unless-stopped
+
+  caddy:
+    # Swap the dev Caddyfile for the prod one, expose 80/443, pass the
+    # domain + admin email through for Let's Encrypt.
+    volumes:
+      - ./caddy/Caddyfile.prod:/etc/caddy/Caddyfile:ro
+      - caddy_data:/data
+      - caddy_config:/config
+    ports: !override
+      - "80:80"
+      - "443:443"
+      - "443:443/udp"
+    environment:
+      PICLOUD_DOMAIN: ${PICLOUD_DOMAIN}
+      PICLOUD_ADMIN_EMAIL: ${PICLOUD_ADMIN_EMAIL}
+    restart: unless-stopped

docker-compose.yml

@@ -0,0 +1,72 @@
+# Default PiCloud stack. Runs the full system end-to-end behind a single
+# Caddy entrypoint, suitable for local development and for verifying that
+# the wiring still works after architectural changes.
+#
+# Caddy is exposed on host port ${PICLOUD_HOST_PORT:-8000} (defaults to
+# 8000 because host port 80 commonly needs sudo on Linux and port 8080 is
+# already in use on this dev machine).
+#
+# For real production deployment, layer the production overrides on top:
+#   docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+
+name: picloud
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB:-picloud}
+      POSTGRES_USER: ${POSTGRES_USER:-picloud}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-picloud}
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    ports:
+      # Exposed in dev so you can poke at the DB with psql. Configurable
+      # because the conventional 5432 is often already in use locally;
+      # the prod overlay removes this mapping entirely.
+      - "127.0.0.1:${PICLOUD_POSTGRES_HOST_PORT:-15432}:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-picloud} -d ${POSTGRES_DB:-picloud}"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+
+  picloud:
+    build:
+      context: .
+      dockerfile: docker/orchestrator.Dockerfile
+    environment:
+      PICLOUD_BIND: 0.0.0.0:8080
+      DATABASE_URL: postgres://${POSTGRES_USER:-picloud}:${POSTGRES_PASSWORD:-picloud}@postgres:5432/${POSTGRES_DB:-picloud}
+      RUST_LOG: ${RUST_LOG:-info}
+    depends_on:
+      postgres:
+        condition: service_healthy
+    expose:
+      - "8080"
+
+  dashboard:
+    build:
+      context: ./dashboard
+      dockerfile: ../docker/dashboard.Dockerfile
+    expose:
+      - "80"
+
+  caddy:
+    image: caddy:2-alpine
+    ports:
+      - "${PICLOUD_HOST_PORT:-8000}:80"
+    volumes:
+      - ./caddy/Caddyfile:/etc/caddy/Caddyfile:ro
+      - caddy_data:/data
+      - caddy_config:/config
+    depends_on:
+      picloud:
+        condition: service_started
+      dashboard:
+        condition: service_started
+
+volumes:
+  postgres_data:
+  caddy_data:
+  caddy_config:

docker/dashboard.Dockerfile

@@ -0,0 +1,28 @@
+# syntax=docker/dockerfile:1.7
+
+# Build stage — produces the static SPA bundle in /app/build.
+FROM node:24-alpine AS builder
+
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN --mount=type=cache,target=/root/.npm npm ci
+
+COPY . .
+RUN npm run build
+
+# Runtime stage — a minimal Caddy that serves the SPA and falls back to
+# index.html for client-side routing. The main reverse-proxy Caddy in
+# the compose stack proxies `/` to this container.
+FROM caddy:2-alpine AS runtime
+
+WORKDIR /srv
+
+COPY --from=builder /app/build /srv
+
+RUN printf ':80 {\n\troot * /srv\n\ttry_files {path} /index.html\n\tfile_server\n\tencode zstd gzip\n\tlog {\n\t\toutput stdout\n\t\tformat console\n\t}\n}\n' > /etc/caddy/Caddyfile
+
+EXPOSE 80
+
+HEALTHCHECK --interval=10s --timeout=2s --retries=3 \
+	CMD wget -qO- http://127.0.0.1/ >/dev/null 2>&1 || exit 1

docker/orchestrator.Dockerfile

@@ -0,0 +1,48 @@
+# syntax=docker/dockerfile:1.7
+
+# Build stage — compiles the `picloud` all-in-one binary against the
+# pinned toolchain from rust-toolchain.toml.
+FROM rust:1.92-slim-bookworm AS builder
+
+WORKDIR /build
+
+# System libs needed for the build (sqlx + reqwest pull rustls so we
+# don't need OpenSSL; pkg-config still helps a few transitive crates).
+RUN apt-get update \
+	&& apt-get install -y --no-install-recommends pkg-config \
+	&& rm -rf /var/lib/apt/lists/*
+
+# Copy the workspace. We could split deps from sources with cargo-chef
+# for better layer caching; defer that until build times become a
+# bottleneck — current cold build is well under a minute on a laptop.
+COPY rust-toolchain.toml Cargo.toml Cargo.lock ./
+COPY crates ./crates
+
+RUN --mount=type=cache,target=/usr/local/cargo/registry \
+	--mount=type=cache,target=/build/target \
+	cargo build --release --bin picloud \
+	&& cp target/release/picloud /tmp/picloud
+
+# Runtime stage — debian-slim is ~30MB and has the CA bundle we need
+# for outbound HTTPS in v1.1+.
+FROM debian:bookworm-slim AS runtime
+
+RUN apt-get update \
+	&& apt-get install -y --no-install-recommends ca-certificates curl \
+	&& rm -rf /var/lib/apt/lists/* \
+	&& useradd --create-home --shell /usr/sbin/nologin --uid 10001 picloud
+
+COPY --from=builder /tmp/picloud /usr/local/bin/picloud
+
+USER picloud
+WORKDIR /home/picloud
+
+ENV PICLOUD_BIND=0.0.0.0:8080 \
+	RUST_LOG=info
+
+EXPOSE 8080
+
+HEALTHCHECK --interval=10s --timeout=2s --start-period=5s --retries=3 \
+	CMD curl -fsS http://127.0.0.1:8080/healthz || exit 1
+
+ENTRYPOINT ["/usr/local/bin/picloud"]