cervo CLAUDE.md

cervo

A demo app for managing static website hosting on a shared VPS, built as an MCP server with FastMCP. Claude Code is the AI/chat interface used to exercise and test the server's tools during development. The whole environment — dev and production alike — runs from docker-compose: caddy is the front door, a worker process runs deployments, and mailcatcher stands in for SMTP in development.

Running

Prerequisite: Docker (with Compose). uv is used for lint/format and can run the test suite directly.

bin/dev    # docker compose up -d — the whole environment

The stack is four services, all sharing the .data volume at /mnt/data:

• app — the MCP server and the public website, one service: uvicorn with WEB_CONCURRENCY worker processes (default 1) importing cervo.asgi — MCP runs stateless, so any worker serves any request. Publishes no port; caddy reverse-proxies it at http://localhost — the homepage (with docs at /docs) — and the MCP endpoint stays http://localhost/mcp.
• worker — the job worker (cervo-worker): one container running WORKER_CONCURRENCY polling threads (default 1) — claiming is atomic in the database, so more threads never double-run a job. Boots first, creates the database tables, and renders the initial Caddyfile (once, before any thread polls).
• caddy — the front door on ports 80/443. Runs on the generated /mnt/data/Caddyfile and serves the sites at http://{slug}.localhost. Its unauthenticated admin API (caddy:2019) is reachable only on the compose network. On a fresh checkout it restarts until the worker first renders the Caddyfile — that's the restart: unless-stopped doing its job, not a bug.
• mail — mailcatcher (SMTP on 1025, web UI at http://localhost:1080). Development mail — the sign-in codes — goes here, not to real SMTP.

Every cervo container runs unprivileged inside: the image bakes in a cervo user (uid 1000) that owns /app and /mnt/data, and caddy runs as the same uid with a sysctl re-allowing :80/:443 (its dev state goes to /tmp — certificates only exist in production, where its volumes are handed over with :U). Host-side, the runtimes still run as root. If a .data directory written by an older root-run stack refuses writes, delete it (dev data is disposable) or chown it to uid 1000.