Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 12 additions & 63 deletions .dockerignore
Original file line number Diff line number Diff line change
@@ -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
41 changes: 41 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
63 changes: 47 additions & 16 deletions Dockerfile
Original file line number Diff line number Diff line change
@@ -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"]
CMD ["late-mcp-http", "--host", "0.0.0.0"]
66 changes: 49 additions & 17 deletions Dockerfile.docker
Original file line number Diff line number Diff line change
@@ -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"]
CMD ["late-mcp-http", "--host", "0.0.0.0"]
2 changes: 2 additions & 0 deletions docs/HTTP_DEPLOYMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
8 changes: 8 additions & 0 deletions tests/test_dockerfile_signals.py
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Loading