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..b776f990 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 +ENV 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..d344d753 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 +ENV 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")