Skip to content

Fix Docker Build: hatchling + README context (ar-r82f.13)#93

Merged
atc964 merged 1 commit into
mainfrom
fix/docker-build
May 28, 2026
Merged

Fix Docker Build: hatchling + README context (ar-r82f.13)#93
atc964 merged 1 commit into
mainfrom
fix/docker-build

Conversation

@atc964
Copy link
Copy Markdown
Collaborator

@atc964 atc964 commented May 28, 2026

Summary

Fix the long-failing Docker Build CI job. The root cause is a missing README.md in the runtime stage of infra/docker/Dockerfilepip install -e . invokes hatchling's metadata validator, which reads the path declared by readme = "README.md" in pyproject.toml and raises OSError: Readme file does not exist: README.md.

Root Causes

  1. README missing in runtime stage (the actual failure). Stage 2 (runtime) copies src/ and pyproject.toml from the builder but never copies README.md. The subsequent RUN pip install --no-cache-dir -e . then fails with OSError: Readme file does not exist: README.md.

  2. Hatchling prepare_metadata_for_build_editable (red herring). The traceback shows AttributeError: module 'hatchling.build' has no attribute 'prepare_metadata_for_build_editable', but this is the normal pip pyproject_hooks fallback path on modern hatchling (the hook is exposed as a function, not a module attribute) and is followed by the real OSError raised during metadata validation. A defensive pin (hatchling>=1.21) is added in pyproject.toml so nothing older can be picked up.

Changes

  • infra/docker/Dockerfile: add COPY --from=builder /build/README.md ./ in the runtime stage so the editable install can read it.
  • pyproject.toml: pin requires = ["hatchling>=1.21"] in [build-system] (defensive).

Before / After (local docker build -f infra/docker/Dockerfile -t ad-buyer-system:test .)

Before:

#19 [runtime 8/9] RUN pip install --no-cache-dir -e .
...
OSError: Readme file does not exist: README.md
ERROR: failed to build: ... pip install --no-cache-dir -e . ... exit code: 1

After:

#20 [runtime 9/10] RUN pip install --no-cache-dir -e .
...
Successfully built ad-buyer-system
Successfully installed ad-buyer-system-0.1.0
naming to docker.io/library/ad-buyer-system:test done

Container runs cleanly: uvicorn comes up, MCP server mounts, GET /health returns 200 OK (matches the CI Docker Build job's Verify health check endpoint exists step).

Test plan

  • Reproduce failure locally on origin/main (90764ab) — confirmed OSError: Readme file does not exist: README.md.
  • docker build -f infra/docker/Dockerfile -t ad-buyer-system:test . succeeds locally.
  • docker run -d -p 8001:8001 ad-buyer-system:test starts and /health returns 200.
  • CI: Docker Build job turns green.
  • CI: Test job stays green (not touched by this PR; Lint failure on main is pre-existing and out of scope).

Out of scope

  • The Lint job is failing on main for an unrelated reason (ruff check on src//tests/). Not addressed here.
  • infra/docker/.dockerignore is present but unused at the current build-context root; leaving it alone to avoid scope creep.

bead: ar-r82f.13

The Docker Build CI job has been failing because the runtime stage of
infra/docker/Dockerfile installs the package with `pip install -e .` but
never copies README.md from the builder stage. pyproject.toml declares
`readme = "README.md"` so hatchling's metadata validation fails with:

    OSError: Readme file does not exist: README.md

Root cause was misdiagnosed earlier as a hatchling backend issue. The
AttributeError on `hatchling.build.prepare_metadata_for_build_editable`
seen in the traceback is the normal pip pyproject_hooks fallback path
(hatchling exposes that hook as a function, not a module attribute); the
real failure is the readme OSError raised during metadata validation.

Changes:
- infra/docker/Dockerfile: copy README.md into the runtime stage so
  `pip install -e .` succeeds.
- pyproject.toml: pin hatchling to >=1.21 to guarantee the build
  backend version pip uses is recent (defensive; not the root cause).

Verified locally: `docker build -f infra/docker/Dockerfile .` now
succeeds and `docker run` produces a healthy uvicorn process responding
200 on /health, matching the CI Docker Build job's verification step.

bead: ar-r82f.13

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@atc964 atc964 merged commit c792144 into main May 28, 2026
2 of 3 checks passed
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