# Deploy to a VPS

The reference deployment is a single small VPS running the container behind Caddy, which handles
TLS. Nothing else is required: no database, no object storage, no queue, no secrets.

## Target topology

```text
client ──HTTPS──▶ Caddy (443) ──HTTP──▶ 127.0.0.1:8000 ──▶ alhorno-mcp container
                        │
                        └── automatic certificates for mcp.alhornoconpapa.com.ar
```

| Name | Serves | Hosting |
| --- | --- | --- |
| `mcp.alhornoconpapa.com.ar` | MCP endpoint `/mcp`, health `/health` | VPS + Caddy |
| `docs.mcp.alhornoconpapa.com.ar` | this documentation | Cloudflare Pages |

## 1. DNS

Create an `A` record (and `AAAA` if the VPS has IPv6) for `mcp.alhornoconpapa.com.ar` pointing at
the VPS, and keep it **DNS only**: grey cloud, not proxied. Caddy terminates TLS for this hostname,
and a proxied record puts Cloudflare in front of it, so long-lived MCP responses then depend on the
proxy's buffering and idle timeouts instead of the container's.

The docs hostname needs no manual record when the zone is already on Cloudflare: adding
`docs.mcp.alhornoconpapa.com.ar` as a Pages custom domain creates the `CNAME` to
`<project>.pages.dev` in the same zone. On another DNS provider, create it manually.

Verify before asking for certificates:

```bash
dig +short mcp.alhornoconpapa.com.ar
dig +short docs.mcp.alhornoconpapa.com.ar
```

## 2. Prepare the VPS

```bash
# Debian or Ubuntu
sudo apt update
sudo apt install -y docker.io docker-compose-v2 git curl ufw

sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"   # log out and back in
```

Firewall: allow SSH, HTTP and HTTPS only.

```bash
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
```

Port 8000 stays closed: Caddy reaches the container over loopback.

## 3. Put the code on the box

```bash
sudo useradd --system --create-home --shell /usr/sbin/nologin alhorno
sudo mkdir -p /srv/alhorno
sudo chown alhorno:alhorno /srv/alhorno

sudo -u alhorno git clone https://github.com/FedeG/al_horno_con_papa_mcp.git /srv/alhorno/app
cd /srv/alhorno/app
sudo -u alhorno cp .env.example .env
```

Edit `.env`:

```dotenv
ALHORNO_TRANSPORT=streamable-http
ALHORNO_HOST=0.0.0.0
ALHORNO_PORT=8000
ALHORNO_ALLOWED_HOSTS=localhost,localhost:*,127.0.0.1,127.0.0.1:*,mcp.alhornoconpapa.com.ar
ALHORNO_LOG_LEVEL=INFO
```

Bind the published port to loopback in `docker-compose.yml`:

```yaml
services:
  mcp:
    ports:
      - "127.0.0.1:8000:8000"
```

Build and start:

```bash
sudo -u alhorno docker compose up -d --build
sudo -u alhorno docker compose ps
curl -fsS http://127.0.0.1:8000/health
```

## 4. Caddy

Install Caddy from the official repository, then edit `/etc/caddy/Caddyfile`:

```caddyfile
mcp.alhornoconpapa.com.ar {
    encode zstd gzip

    # The MCP transport is stateless, but long-lived responses are normal.
    reverse_proxy 127.0.0.1:8000 {
        header_up Host {host}
        flush_interval -1
    }

    log {
        output file /var/log/caddy/mcp-access.log {
            roll_size 10MiB
            roll_keep 5
        }
        format json
    }
}
```

Reload and check:

```bash
sudo systemctl reload caddy
curl -fsS https://mcp.alhornoconpapa.com.ar/health
```

`header_up Host {host}` keeps the public hostname in the proxied request, which is what the
transport's allowlist checks. `flush_interval -1` disables response buffering, so streamed MCP
responses are not delayed.

### Verify the MCP handshake through TLS

```bash
curl -sS -X POST https://mcp.alhornoconpapa.com.ar/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' \
  -o /dev/null -w '%{http_code}\n'
```

`200` means DNS, TLS, Caddy and the allowlist all line up.

## 5. Run without Docker (optional)

If you prefer a plain process, install the wheel and use a systemd unit:

```bash
sudo -u alhorno uv tool install /srv/alhorno/app
```

```ini
# /etc/systemd/system/alhorno-mcp.service
[Unit]
Description=alhorno-mcp
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=alhorno
Group=alhorno
Environment=ALHORNO_TRANSPORT=streamable-http
Environment=ALHORNO_HOST=127.0.0.1
Environment=ALHORNO_PORT=8000
Environment=ALHORNO_ALLOWED_HOSTS=localhost,localhost:*,127.0.0.1,127.0.0.1:*,mcp.alhornoconpapa.com.ar
ExecStart=/home/alhorno/.local/bin/alhorno-mcp serve
Restart=on-failure
RestartSec=3

NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/home/alhorno

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now alhorno-mcp
sudo systemctl status alhorno-mcp
```

The service binds to loopback, so Caddy keeps doing TLS exactly as before.

## 6. Publish the documentation

Cloudflare Pages builds and serves the docs site, connected directly to the GitHub repository.
GitHub Actions only checks work: it regenerates `requirements-docs.txt`, runs
`mkdocs build --strict`, and never deploys.

Create the Pages project once:

1. **Workers & Pages → Create application → Pages → Import an existing Git repository**, pick the
   repository, and use these settings:

   | Setting | Value |
   | --- | --- |
   | Production branch | `main` |
   | Build command | `pip install -r requirements-docs.txt && mkdocs build --strict` |
   | Build directory | `site` |

2. Add two environment variables under **Settings → Environment variables**:

   | Variable | Value |
   | --- | --- |
   | `PYTHON_VERSION` | `3.12` |
   | `NO_MKDOCS_2_WARNING` | `1` |

3. Under **Custom domains**, add `docs.mcp.alhornoconpapa.com.ar` and let Cloudflare create the
   record and the certificate.

4. Every push to `main` rebuilds the site, and every pull request gets a preview URL.

`requirements-docs.txt` is generated from `uv.lock`, so Pages installs exactly the versions CI
tests against:

```bash
uv export --only-group docs --no-emit-project --no-hashes --output-file requirements-docs.txt
```

CI fails when the file drifts from the lockfile, so regenerate and commit it whenever the docs
dependencies change.

Two details matter on a fresh project. There is no `requirements.txt`, so the automatic dependency
install finds nothing and the build command has to install the file itself. And the Markdown build
reads `CHANGELOG.md` from the repository root through `pymdownx.snippets`, so the build has to run
with the repository root as its working directory, which is the default.

The build also writes `robots.txt`, `sitemap.xml` (from MkDocs, with the 404 page excluded),
`llms.txt`, `llms-full.txt` and a Markdown copy of every page, so both crawlers and LLMs can read
the documentation without HTML.


## 7. Weekly routine

New recipes appear weekly. Recipes are immutable; only tags and relations change.

```bash
cd /srv/alhorno/app
sudo -u alhorno uv run alhorno-mcp sync --check   # exit 1 means upstream changed
sudo -u alhorno uv run alhorno-mcp sync
git diff --stat src/alhorno_mcp/data/recipes.json
```

Commit the refreshed snapshot, then roll it out:

```bash
sudo -u alhorno docker compose up -d --build
curl -fsS https://mcp.alhornoconpapa.com.ar/health
```

If you mount the snapshot instead, replace the file in the volume and restart the container: the
snapshot is read once at startup.

## Monitoring and rollback

- **Health:** poll `GET /health` from an external monitor. It returns the version and the number of
  recipes, so a truncated snapshot is visible immediately.
- **Logs:** `docker compose logs -f mcp` for tool calls, `/var/log/caddy/mcp-access.log` for HTTP
  status codes. Tool errors are visible in the response, not the log, by design.
- **Rollback:** `git checkout <previous-tag> && docker compose up -d --build`. The image is
  self-contained, so a rollback is one command and needs no data migration.

## Abuse and rate limiting

The endpoint is public and read-only, with no authentication and no per-caller state. A simple
`limit`/`offset` paging contract keeps responses small, but nothing prevents a client from calling
it in a loop. If that becomes a problem, put the hostname behind a proxy with a request-rate rule
(Cloudflare, or Caddy with a rate-limit plugin) rather than adding tokens to this server: the data
is public anyway, so the goal is availability, not secrecy.
