Skip to content

build(mcp): multi-stage, non-root Docker image with cached dependencies - #115

Closed
Ooscaar wants to merge 2 commits into
developfrom
chore/docker-image-best-practices
Closed

Ooscaar wants to merge 2 commits into
developfrom
chore/docker-image-best-practices

Conversation

@Ooscaar

@Ooscaar Ooscaar commented Nov 18, 2026

Copy link
Copy Markdown
Member

What changes

The image Railway deploys (Dockerfile), and its plain-Docker copy (Dockerfile.docker), now follow Docker's and uv's best practices.

Before After
Dependency layer Rebuilt on every deploy: src was copied before uv sync, and uv.lock changes on every spec regeneration (139 commits touched it in 7 days) Installed from a uv export that leaves out the project's version. The exported list is byte-identical across version bumps, so the layer is reused
Bytecode None. Every new container compiles each import on startup Compiled at build time (UV_COMPILE_BYTECODE=1)
Runtime image uv image, with uv, src, the lockfile and an editable install python:3.12-slim-bookworm with only the virtualenv. The project is a non-editable install
User root app (uid 10001). The venv is root-owned and read-only to it
Versions uv:python3.12-bookworm-slim (floating uv) uv pinned to 0.13.7, Python 3.12-slim-bookworm
Build context Denylist .dockerignore: apps-src, openapi.yaml, scripts, .railway etc. were sent Allowlist: pyproject.toml, uv.lock, README.md, src/
Logs Default buffering PYTHONUNBUFFERED=1

These are kept as they were:

The Railway Dockerfile has no BuildKit cache mount, because Railway requires the mount ID to carry the service ID (s/<service-id>-…). The layer reuse above gives the same benefit without one.

CI gets a new docker job. It builds both Dockerfiles and checks four things:

  • the container runs as a non-root user
  • /health answers
  • POST /mcp without a token gets the 401 OAuth challenge
  • docker stop exits 0

tests/test_dockerfile_signals.py also now checks that both Dockerfiles set a non-root USER.

Verified locally

Local Docker isn't available (no access to the Docker socket), so I ran each image stage's commands in a clean directory. The build context was exactly what .dockerignore allows. The server then ran from the resulting virtualenv, with the venv made read-only, src deleted, and the working directory outside the repo. The CI job above does the real docker build.

  • Export: the exports for 1.4.1853 and 1.4.1855 differ only in the header line that names the output path, and that path is fixed inside the image.

  • Builder: uv sync installed only the project (Installed 1 package) on top of the exported dependencies. It compiled 3,423 files.

  • Package data is in the installed package: landing.html, logo.svg, the MCP App bundle and its fonts.

  • 4 workers: /health returned 503 until all were ready, then 200.

  • Endpoints:

    • GET / serves JSON and the HTML landing page.
    • OAuth protected-resource metadata is served.
    • POST /messages/ returns 410 with the migration body.
    • /mcp without a token returns 401.
    • initialize succeeds on /mcp, /sse and /chatgpt.
  • Tools: 8 of 8 tools/list calls across workers returned 44 tools. A real docs_search tool call succeeded.

  • With ZERNIO_MCP_APPS=1:

    • ui://zernio/v2/app.html is served at 501 KB.
    • All 3 fonts return 200.
    • All 9 app tools are registered.
  • Shutdown: SIGTERM shuts all workers down gracefully, with exit code 0.

  • No runtime writes: no .pyc files were written at runtime.

  • Startup time to a healthy 4-worker server, measured twice each:

    Run No bytecode (today) Precompiled (this PR)
    1 13.5 s 9.7 s
    2 13.3 s 9.8 s
  • Tests: pytest tests/test_dockerfile_signals.py tests/test_mcp_sse_retired.py → 10 passed.

Rollout

Nothing to configure: Railway builds Dockerfile as before. Merging deploys production. If it fails to come up, the deploy health check keeps the current deployment serving. To roll back, revert this PR.

🤖 Generated with Claude Code

Ooscaar and others added 2 commits November 18, 2026 22:50
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 <noreply@anthropic.com>
…eads it

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Ooscaar

Ooscaar commented Nov 19, 2026

Copy link
Copy Markdown
Member Author

Closing: Railway build logs show the Docker build is ~6 s of a ~35 s deploy (uv sync ~2 s), so the caching gain is negligible. Not worth the change for now.

@Ooscaar Ooscaar closed this Nov 19, 2026
@Ooscaar
Ooscaar deleted the chore/docker-image-best-practices branch November 19, 2026 10:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant