Docker¶
The image is a multi-stage build: uv resolves the lockfile in a builder stage, and the runtime
stage copies only the virtualenv, the package and the snapshot. No compiler, no lockfile and no
build tools reach production.
Build¶
The build is reproducible from uv.lock: the builder runs uv sync --locked --no-dev, so a lock
change is the only thing that changes dependency versions.
Run¶
The image defaults are already production-shaped:
| Setting | Value |
|---|---|
| Command | alhorno-mcp serve |
| Transport | streamable-http |
| Bind address | 0.0.0.0:8000 |
| Endpoint | POST /mcp |
| Health probe | GET /health |
| User | app (uid 10001), unprivileged |
| Logs | stderr |
Check it:
The host allowlist is the usual first problem¶
The container binds to 0.0.0.0, but the HTTP transport still rejects unknown Host headers with
421 Misdirected Request. Add the name clients use:
docker run --rm -p 8000:8000 \
-e ALHORNO_ALLOWED_HOSTS="localhost,localhost:*,127.0.0.1,127.0.0.1:*,mcp.alhornoconpapa.com.ar" \
alhorno-mcp:local
Docker Compose¶
The repository ships a Compose file that builds the local Dockerfile, publishes port 8000, reads
environment values from .env and defines a health check.
docker compose ps should report healthy. To stop and remove:
Mounting a snapshot¶
ALHORNO_DATA_DIR lets the container read recipes.json from a volume instead of the packaged
copy. This is how you ship a weekly update without rebuilding:
The container user is uid 10001, so the mounted file must be readable by it:
Behind a reverse proxy¶
Bind the published port to loopback only, and let Caddy or nginx terminate TLS:
Keep ALHORNO_HOST=0.0.0.0 inside the container; the proxy connects over the published port. See
Deploy to a VPS for the full setup.
Updating¶
git pull
uv run alhorno-mcp sync # optional: refresh the snapshot
docker compose up -d --build
docker compose ps
A restart is enough to load a new snapshot. Rebuilding is only needed when code or dependencies change.
Image details¶
builder python:3.12-slim + uv
uv sync --locked --no-dev → /app/.venv
runtime python:3.12-slim
/app/.venv, /app/src
USER app
HEALTHCHECK every 30s against /health
- The virtualenv sits on
PATH, soalhorno-mcpis the entrypoint. PYTHONUNBUFFERED=1andPYTHONDONTWRITEBYTECODE=1keep logs immediate and the filesystem clean..dockerignoreexcludes tests, docs, git metadata and local caches, so the build context stays small and the image ships no test data.
Troubleshooting¶
| Symptom | Check |
|---|---|
| Container restarts in a loop | docker logs <id>: a snapshot or settings error exits with code 1 and a message. |
curl: (56) Recv failure on startup |
The process is still loading; the health check needs a few seconds. |
421 from a client |
The public hostname is missing from ALHORNO_ALLOWED_HOSTS. |
permission denied reading a mounted snapshot |
The file must be readable by uid 10001. |
| Tools missing in the host | The host is pointing at the wrong path or port; POST /mcp is the only endpoint. |