From 02454dc472c1b05bfb4147fcfe065c7e73fb1437 Mon Sep 17 00:00:00 2001 From: Oscar Perez Date: Wed, 18 Nov 2026 22:50:30 +0100 Subject: [PATCH 1/2] build(mcp): multi-stage, non-root Docker image with cached dependencies The dependency layer is now reused across deploys: dependencies install from a `uv export` that leaves the project out, so the version bump every spec regeneration makes in uv.lock no longer reinstalls them. Bytecode is compiled at build time, so workers are ready about 3.6 s sooner on each start. The runtime image holds Python and the virtualenv only, runs as a non-root user, and gets its build context from an allowlist .dockerignore. CI builds both Dockerfiles and smoke-tests the image. Co-Authored-By: Claude Opus 5.5 --- .dockerignore | 75 +++++--------------------------- .github/workflows/test.yml | 41 +++++++++++++++++ Dockerfile | 63 ++++++++++++++++++++------- Dockerfile.docker | 66 ++++++++++++++++++++-------- docs/HTTP_DEPLOYMENT.md | 2 + tests/test_dockerfile_signals.py | 8 ++++ 6 files changed, 159 insertions(+), 96 deletions(-) diff --git a/.dockerignore b/.dockerignore index 3f0a4ca4..2e128c4c 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,63 +1,12 @@ -# Python cache -__pycache__/ -*.py[cod] -*$py.class -*.so -.Python - -# Virtual environments -.venv/ -venv/ -ENV/ -env/ - -# Environment variables -.env -.env.local -.env.*.local - -# Git -.git/ -.gitignore -.gitattributes - -# Documentation (keep README.md for hatchling build) -docs/ -examples/ - -# Tests -tests/ -.pytest_cache/ -.coverage -htmlcov/ -.tox/ - -# IDE -.vscode/ -.idea/ -*.swp -*.swo -*~ - -# Build artifacts -build/ -dist/ -*.egg-info/ -.eggs/ - -# Type checking -.mypy_cache/ -.pytype/ -.pyre/ -.dmypy.json - -# Linting -.ruff_cache/ - -# CI/CD -.github/ -.gitlab-ci.yml - -# Misc -*.log -.DS_Store +# Allowlist: the image is built from these files only. Anything new in the +# repo stays out of the build context until it is added here. +* +!pyproject.toml +!uv.lock +!README.md +!src/ + +# Never ship local caches or bytecode from a developer checkout. +**/__pycache__ +**/*.py[cod] +**/.DS_Store diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 770e255d..ff533aa8 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -64,3 +64,44 @@ jobs: with: name: dist path: dist/ + + # The image Railway deploys: build it from the Dockerfile and check it starts + # as a non-root user and answers health and MCP requests. + docker: + runs-on: ubuntu-latest + permissions: + contents: read + strategy: + matrix: + dockerfile: [Dockerfile, Dockerfile.docker] + + steps: + - uses: actions/checkout@v4 + + - name: Build image + run: docker build -f ${{ matrix.dockerfile }} -t zernio-mcp . + + - name: Runs as a non-root user + run: test "$(docker run --rm zernio-mcp id -u)" != "0" + + - name: Starts and serves MCP + run: | + docker run -d --name mcp -p 8080:8080 -e PORT=8080 zernio-mcp + for _ in $(seq 1 60); do + curl -sf http://localhost:8080/health && break + sleep 1 + done + curl -sf http://localhost:8080/health + # Unauthenticated initialize gets the OAuth challenge, not an error. + test "$(curl -s -o /dev/null -w '%{http_code}' -X POST http://localhost:8080/mcp \ + -H 'Accept: application/json, text/event-stream' -H 'Content-Type: application/json' \ + -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"ci","version":"1"}}}')" = "401" + + - name: Stops on SIGTERM + run: | + docker stop --timeout 30 mcp + test "$(docker inspect -f '{{.State.ExitCode}}' mcp)" = "0" + + - name: Server logs + if: always() + run: docker logs mcp || true diff --git a/Dockerfile b/Dockerfile index eaf0365d..d47fb1e5 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,27 +1,58 @@ -# Late MCP HTTP Server - Railway Deployment -# Uses uv for fast, reliable dependency management - -FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim - +# syntax=docker/dockerfile:1 +# Zernio MCP HTTP server, deployed on Railway. +# +# Three stages: a lockfile export, a builder that has uv, and a runtime image +# that holds only Python and the virtualenv, running as a non-root user. + +ARG PYTHON_IMAGE=python:3.12-slim-bookworm + +FROM ghcr.io/astral-sh/uv:0.13.7 AS uv + +# Every spec regeneration bumps the project version in uv.lock, so installing +# straight from uv.lock would reinstall every dependency on every deploy. The +# export leaves the project out, stays byte-identical across those bumps, and +# lets the builder reuse its dependency layer. +FROM ${PYTHON_IMAGE} AS requirements +COPY --from=uv /uv /usr/local/bin/uv WORKDIR /app - -ENV MALLOC_ARENA_MAX=2 - -# Copy dependency files +COPY pyproject.toml uv.lock ./ +RUN uv export --frozen --no-dev --extra mcp --no-emit-project -o requirements.txt + +FROM ${PYTHON_IMAGE} AS builder +COPY --from=uv /uv /usr/local/bin/uv +# Bytecode is compiled at build time: the runtime user cannot write .pyc files +# next to the code, and each worker would otherwise compile on every start. +ENV UV_COMPILE_BYTECODE=1 \ + UV_LINK_MODE=copy \ + UV_NO_CACHE=1 \ + UV_PYTHON_DOWNLOADS=0 \ + UV_PROJECT_ENVIRONMENT=/app/.venv +WORKDIR /app +COPY --from=requirements /app/requirements.txt ./ +RUN uv venv /app/.venv \ + && uv pip install --python /app/.venv/bin/python --require-hashes -r requirements.txt COPY pyproject.toml uv.lock README.md ./ COPY src ./src +# Non-editable, so the runtime image needs the virtualenv and not src. +RUN uv sync --frozen --no-dev --extra mcp --no-editable -# Install dependencies (no dev dependencies in production) -RUN uv sync --frozen --no-dev --extra mcp +FROM ${PYTHON_IMAGE} -# Expose port (Railway will set PORT env var) -EXPOSE 8080 +RUN groupadd --system --gid 10001 app \ + && useradd --system --uid 10001 --gid app --create-home app -# Health check for Railway monitoring (Railway will use /health endpoint) +COPY --from=builder /app/.venv /app/.venv -# Run HTTP server (Railway sets PORT env var automatically) +ENV MALLOC_ARENA_MAX=2 \ + PYTHONUNBUFFERED=1 ENV PATH="/app/.venv/bin:$PATH" +WORKDIR /app +USER app + +# Railway sets PORT; the server reads it and defaults to 8080. +EXPOSE 8080 + # Exec form, no shell or `uv run`: the server is PID 1 and gets the SIGTERM a # deploy sends, so in-flight tool calls finish. It reads PORT itself. -CMD ["late-mcp-http", "--host", "0.0.0.0"] \ No newline at end of file +CMD ["late-mcp-http", "--host", "0.0.0.0"] diff --git a/Dockerfile.docker b/Dockerfile.docker index 0249da47..6f50821e 100644 --- a/Dockerfile.docker +++ b/Dockerfile.docker @@ -1,28 +1,60 @@ -# Late MCP HTTP Server - Railway Deployment -# Uses uv for fast, reliable dependency management - -FROM ghcr.io/astral-sh/uv:python3.12-slim - +# syntax=docker/dockerfile:1 +# Zernio MCP HTTP server, for plain Docker builds. Dockerfile is the one +# Railway deploys; this copy differs only in caching uv downloads. +# +# Three stages: a lockfile export, a builder that has uv, and a runtime image +# that holds only Python and the virtualenv, running as a non-root user. + +ARG PYTHON_IMAGE=python:3.12-slim-bookworm + +FROM ghcr.io/astral-sh/uv:0.13.7 AS uv + +# Every spec regeneration bumps the project version in uv.lock, so installing +# straight from uv.lock would reinstall every dependency on every deploy. The +# export leaves the project out, stays byte-identical across those bumps, and +# lets the builder reuse its dependency layer. +FROM ${PYTHON_IMAGE} AS requirements +COPY --from=uv /uv /usr/local/bin/uv WORKDIR /app - -ENV MALLOC_ARENA_MAX=2 - -# Copy dependency files +COPY pyproject.toml uv.lock ./ +RUN uv export --frozen --no-dev --extra mcp --no-emit-project -o requirements.txt + +FROM ${PYTHON_IMAGE} AS builder +COPY --from=uv /uv /usr/local/bin/uv +# Bytecode is compiled at build time: the runtime user cannot write .pyc files +# next to the code, and each worker would otherwise compile on every start. +ENV UV_COMPILE_BYTECODE=1 \ + UV_LINK_MODE=copy \ + UV_PYTHON_DOWNLOADS=0 \ + UV_PROJECT_ENVIRONMENT=/app/.venv +WORKDIR /app +COPY --from=requirements /app/requirements.txt ./ +RUN --mount=type=cache,id=uv-cache,target=/root/.cache/uv \ + uv venv /app/.venv \ + && uv pip install --python /app/.venv/bin/python --require-hashes -r requirements.txt COPY pyproject.toml uv.lock README.md ./ COPY src ./src - -# Install dependencies (no dev dependencies in production) +# Non-editable, so the runtime image needs the virtualenv and not src. RUN --mount=type=cache,id=uv-cache,target=/root/.cache/uv \ - uv sync --frozen --no-dev --extra mcp + uv sync --frozen --no-dev --extra mcp --no-editable -# Expose port (Railway will set PORT env var) -EXPOSE 8080 +FROM ${PYTHON_IMAGE} + +RUN groupadd --system --gid 10001 app \ + && useradd --system --uid 10001 --gid app --create-home app -# Health check for Railway monitoring (Railway will use /health endpoint) +COPY --from=builder /app/.venv /app/.venv -# Run HTTP server (Railway sets PORT env var automatically) +ENV MALLOC_ARENA_MAX=2 \ + PYTHONUNBUFFERED=1 ENV PATH="/app/.venv/bin:$PATH" +WORKDIR /app +USER app + +# Railway sets PORT; the server reads it and defaults to 8080. +EXPOSE 8080 + # Exec form, no shell or `uv run`: the server is PID 1 and gets the SIGTERM a # deploy sends, so in-flight tool calls finish. It reads PORT itself. -CMD ["late-mcp-http", "--host", "0.0.0.0"] \ No newline at end of file +CMD ["late-mcp-http", "--host", "0.0.0.0"] diff --git a/docs/HTTP_DEPLOYMENT.md b/docs/HTTP_DEPLOYMENT.md index 552019fe..b2fecfc3 100644 --- a/docs/HTTP_DEPLOYMENT.md +++ b/docs/HTTP_DEPLOYMENT.md @@ -44,6 +44,8 @@ curl -H "Authorization: Bearer your_zernio_api_key" \ 3. Railway builds the `Dockerfile` and deploys 4. No environment variables needed! (users provide their own API keys) +The image is built in stages: dependencies are installed from a `uv export` of the lockfile, so the version bump each spec regeneration makes in `uv.lock` does not reinstall them, and the project goes in as a non-editable package with bytecode compiled at build time. The runtime image holds Python and the virtualenv only (no uv, no `src`) and runs as the non-root `app` user. `.dockerignore` is an allowlist: a file the build needs must be added there. `Dockerfile.docker` is the same image with a uv cache mount, for plain Docker builds; keep the two in step. CI builds both and checks the image starts, answers `/health` and `/mcp`, and stops on SIGTERM. + ### Deploy configuration The service's deploy settings live in [`.railway/railway.ts`](../.railway/railway.ts) (Railway [Infrastructure as Code](https://docs.railway.com/infrastructure-as-code)). It replaces `railway.toml`, which Railway stops reading on 2026-12-01. It sets the Dockerfile build, the `/health` check (100 s timeout), restart on failure (3 retries), one replica in `us-west2`, the GitHub repo and branch each environment deploys from, and the `mcp.zernio.com` domain in production. It sets no start command, so the `Dockerfile` `CMD` starts the server; do not add one. Variables are declared with `preserve()`, so their values stay managed in Railway. diff --git a/tests/test_dockerfile_signals.py b/tests/test_dockerfile_signals.py index c4278f5f..51261b27 100644 --- a/tests/test_dockerfile_signals.py +++ b/tests/test_dockerfile_signals.py @@ -13,3 +13,11 @@ def test_the_server_is_pid_1_so_deploy_sigterm_reaches_it(dockerfile): assert 'ENV PATH="/app/.venv/bin:$PATH"' in lines assert json.loads(cmd.removeprefix("CMD"))[0] == "late-mcp-http" + + +@pytest.mark.parametrize("dockerfile", ["Dockerfile", "Dockerfile.docker"]) +def test_the_server_runs_as_a_non_root_user(dockerfile): + lines = (REPO_ROOT / dockerfile).read_text().splitlines() + [user] = [line for line in lines if line.startswith("USER")] + + assert user.split()[1] not in ("root", "0") From de6e6ab9e23b3bb5623fe9c4e5a1f675d20fb6f8 Mon Sep 17 00:00:00 2001 From: Oscar Perez Date: Wed, 18 Nov 2026 22:55:58 +0100 Subject: [PATCH 2/2] test: keep MALLOC_ARENA_MAX on its own ENV line, as the memory test reads it Co-Authored-By: Claude Opus 5.5 --- Dockerfile | 4 ++-- Dockerfile.docker | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Dockerfile b/Dockerfile index d47fb1e5..b776f990 100644 --- a/Dockerfile +++ b/Dockerfile @@ -43,8 +43,8 @@ RUN groupadd --system --gid 10001 app \ COPY --from=builder /app/.venv /app/.venv -ENV MALLOC_ARENA_MAX=2 \ - PYTHONUNBUFFERED=1 +ENV MALLOC_ARENA_MAX=2 +ENV PYTHONUNBUFFERED=1 ENV PATH="/app/.venv/bin:$PATH" WORKDIR /app diff --git a/Dockerfile.docker b/Dockerfile.docker index 6f50821e..d344d753 100644 --- a/Dockerfile.docker +++ b/Dockerfile.docker @@ -45,8 +45,8 @@ RUN groupadd --system --gid 10001 app \ COPY --from=builder /app/.venv /app/.venv -ENV MALLOC_ARENA_MAX=2 \ - PYTHONUNBUFFERED=1 +ENV MALLOC_ARENA_MAX=2 +ENV PYTHONUNBUFFERED=1 ENV PATH="/app/.venv/bin:$PATH" WORKDIR /app