# 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

```bash
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

```bash
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:

```bash
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:

```bash
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.

```bash
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:

```bash
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:

```yaml
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:

```bash
chmod 0644 data/recipes.json
```

### Behind a reverse proxy

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

```yaml
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](deploy.md) for the full setup.

## Updating

```bash
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

```text
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. |
