Skip to content

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

docker build -t alhorno-mcp:local .

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

docker run --rm -p 8000:8000 alhorno-mcp:local

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:

curl -fsS http://127.0.0.1:8000/health

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.

cp .env.example .env
docker compose up -d
docker compose ps
docker compose logs -f mcp

docker compose ps should report healthy. To stop and remove:

docker compose down

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:

services:
  mcp:
    environment:
      ALHORNO_DATA_DIR: /data
    volumes:
      - ./data:/data:ro

The container user is uid 10001, so the mounted file must be readable by it:

chmod 0644 data/recipes.json

Behind a reverse proxy

Bind the published port to loopback only, and let Caddy or nginx terminate TLS:

ports:
  - "127.0.0.1:8000:8000"

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, so alhorno-mcp is the entrypoint.
  • PYTHONUNBUFFERED=1 and PYTHONDONTWRITEBYTECODE=1 keep logs immediate and the filesystem clean.
  • .dockerignore excludes 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.