mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
fix(docker): pass RUNTIME_HOME=/root for root bake targets (#4445)
## Description Fixes #4443. The four root bake targets (`runtime`, `runtime-code`, `runtime-slim`, `runtime-code-slim`) set `RUNTIME_USER=root` but not `RUNTIME_HOME`, so the Dockerfile default `/home/nonroot` was used for `VOLUME` and `WORKDIR` while the process runs with `HOME=/root`. `~/.headroom` therefore landed in the container layer instead of the declared volume. Passing `RUNTIME_HOME=/root` fixes the two python-slim targets, but the two slim targets build the distroless `runtime-slim` stage, which declared no `ARG RUNTIME_HOME` and no `VOLUME` at all, so the arg was a silent no-op there. That stage now declares `ARG RUNTIME_HOME` and `VOLUME ${RUNTIME_HOME}/.headroom`, and since distroless has no shell for `RUN mkdir`, the state directory is built in a small `runtime-slim-state` stage and copied in owned by `RUNTIME_USER`. Closes #4443 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `docker-bake.hcl`: pass `RUNTIME_HOME = "/root"` in the four targets that set `RUNTIME_USER = "root"`. - `Dockerfile`: new `runtime-slim-state` stage (`python:${PYTHON_VERSION}-slim`) that creates `/state/.headroom`; the distroless `runtime-slim` stage now declares `ARG RUNTIME_HOME=/home/nonroot`, copies that directory to `${RUNTIME_HOME}/` with `--chown=${RUNTIME_USER}:${RUNTIME_USER}`, and declares `VOLUME ${RUNTIME_HOME}/.headroom`, matching the python-slim stage. - `tests/test_release_workflows.py`: `test_docker_bake_runtime_args_are_declared_by_the_selected_stage` walks every bake target, resolves the Dockerfile stage it builds (including inherited parent stages), and checks that each `RUNTIME_*` arg it passes is declared by that stage, that root targets use `/root`, and that the stage puts `VOLUME ${RUNTIME_HOME}/.headroom` under the home it was given. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text $ pytest tests/test_release_workflows.py -q # head59bd12d58 passed, 1 warning in 6.41s $ pytest tests/test_release_workflows.py -q -k runtime_args # new test on upstream main E AssertionError: runtime: root target needs /root 1 failed, 57 deselected, 1 warning in 0.77s $ pytest tests/test_release_workflows.py -q -k runtime_args # new test onae30825(bake fix only) E AssertionError: runtime-slim: stage runtime-slim does not declare {'RUNTIME_HOME'} 1 failed, 57 deselected, 1 warning in 0.40s $ ruff check tests/test_release_workflows.py All checks passed! $ ruff format --check tests/test_release_workflows.py 1 file already formatted ``` ## Real Behavior Proof - Environment: local Linux, Python 3.14, pytest (no Docker daemon locally); Docker images built and run on a GitHub-hosted `ubuntu-latest` runner (Docker 28.0.4, buildx v0.38.1, `linux/amd64`) by a scratch workflow in my fork on top of `59bd12d`: [run](https://github.com/drakeo338/headroom/actions/runs/40957966633), [workflow](https://github.com/drakeo338/headroom/blob/11ce83618e808688bea5a60cd0545e9bae511d4a/.github/workflows/image-evidence.yml) - Exact command / steps: ran the new test against upstream `main`, against `ae30825` (bake args only) and against head `59bd12d` (bake args plus the `runtime-slim` stage change); full `tests/test_release_workflows.py` on head. On the runner: `docker buildx bake -f docker-bake.hcl --print runtime runtime-code runtime-slim runtime-code-slim`; `docker buildx bake -f docker-bake.hcl --set '*.platform=linux/amd64' --load` of the same four targets; `docker inspect` of `Config.User`, `Config.WorkingDir`, `Config.Volumes` per image; per image, one container writes `/root/.headroom/probe` on a named volume and a second container on the same volume reads it back, plus `docker create` without `-v` to list the image's own mounts - Observed result: the test fails on `main` (root targets have no `RUNTIME_HOME`), fails on `ae30825` (the distroless `runtime-slim` stage does not declare `RUNTIME_HOME`, so the slim targets ignore it), passes on `59bd12d`; all 58 tests in the file pass. The bake plan resolves `runtime`/`runtime-code` to stage `runtime` and `runtime-slim`/`runtime-code-slim` to stage `runtime-slim`, all with `RUNTIME_USER=root RUNTIME_HOME=/root`. Inspected: `runtime` and `runtime-code` have `User="root" WorkingDir="/root" Volumes={"/root/.headroom":{}}`; `runtime-slim` and `runtime-code-slim` have `User="root" WorkingDir="/app" Volumes={"/root/.headroom":{}}`. In all four the probe written by the first container is read back by the second, and `docker create` shows `type=volume destination=/root/.headroom` - Not tested: mypy (no Python package code changed) ## Runtime Rollout Safety - Rollout-managed feature(s): none - Minimum rollout channel: n/a - Stable/default behavior changed: yes, the root images keep `~/.headroom` on the declared volume, and the distroless slim images now declare that volume - Kill switch / disable path: n/a - Unsafe override required: no - Qualification impact: none - Rollback path: revert this PR ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Screenshots (if applicable) N/A ## Additional Notes N/A <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4445" target="_blank"><picture><source media="(prefers-color-scheme: dark)" srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4" alt="Devin Review"></picture></a> <!-- devin-review-badge-end --> --------- Co-authored-by: JD Davis <mxjerrett@gmail.com>
This commit is contained in:
co-authored by
JD Davis
parent
6ef52c2047
commit
670767eeb4
+13
@@ -214,14 +214,23 @@ ENTRYPOINT ["headroom", "proxy"]
|
||||
# Keep host and port defaults in the CLI so HEADROOM_HOST and HEADROOM_PORT
|
||||
# remain authoritative for the published image.
|
||||
|
||||
# Distroless has no shell, so the ~/.headroom state directory cannot be made
|
||||
# with RUN there. Build it here and COPY it in with the right owner (#4443).
|
||||
FROM python:${PYTHON_VERSION}-slim AS runtime-slim-state
|
||||
RUN mkdir -p /state/.headroom
|
||||
|
||||
FROM ${DISTROLESS_IMAGE} AS runtime-slim
|
||||
|
||||
ARG RUNTIME_USER=nonroot
|
||||
ARG RUNTIME_HOME=/home/nonroot
|
||||
ARG PYTHON_SITE_PACKAGES
|
||||
|
||||
COPY --from=builder ${PYTHON_SITE_PACKAGES} ${PYTHON_SITE_PACKAGES}
|
||||
# Native Rust reverse proxy binary (issue #976).
|
||||
COPY --from=builder /usr/local/bin/headroom-proxy /usr/local/bin/headroom-proxy
|
||||
# Owned by the runtime user so the volume below is writable (user and group
|
||||
# are both named after RUNTIME_USER in the distroless image).
|
||||
COPY --from=runtime-slim-state --chown=${RUNTIME_USER}:${RUNTIME_USER} /state/ ${RUNTIME_HOME}/
|
||||
|
||||
USER ${RUNTIME_USER}
|
||||
WORKDIR /app
|
||||
@@ -231,6 +240,10 @@ ENV HEADROOM_HOST=127.0.0.1 \
|
||||
PYTHONDONTWRITEBYTECODE=1 \
|
||||
PYTHONPATH=${PYTHON_SITE_PACKAGES}
|
||||
|
||||
# Same persistent-state volume as the python-slim stage; pass
|
||||
# --build-arg RUNTIME_HOME=/root when building with RUNTIME_USER=root.
|
||||
VOLUME ${RUNTIME_HOME}/.headroom
|
||||
|
||||
EXPOSE 8787
|
||||
|
||||
# This stage is distroless, so there is no shell to expand ${HEADROOM_PORT}.
|
||||
|
||||
@@ -21,6 +21,7 @@ target "runtime" {
|
||||
args = {
|
||||
HEADROOM_EXTRAS = "proxy,bedrock,redis"
|
||||
RUNTIME_USER = "root"
|
||||
RUNTIME_HOME = "/root"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -39,6 +40,7 @@ target "runtime-code" {
|
||||
args = {
|
||||
HEADROOM_EXTRAS = "proxy,code,bedrock,redis"
|
||||
RUNTIME_USER = "root"
|
||||
RUNTIME_HOME = "/root"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -57,6 +59,7 @@ target "runtime-slim" {
|
||||
args = {
|
||||
HEADROOM_EXTRAS = "proxy,bedrock,redis"
|
||||
RUNTIME_USER = "root"
|
||||
RUNTIME_HOME = "/root"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -75,6 +78,7 @@ target "runtime-code-slim" {
|
||||
args = {
|
||||
HEADROOM_EXTRAS = "proxy,code,bedrock,redis"
|
||||
RUNTIME_USER = "root"
|
||||
RUNTIME_HOME = "/root"
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -156,6 +156,69 @@ def test_every_published_docker_variant_includes_bedrock_auth_dependencies() ->
|
||||
assert {"boto3", "botocore"} <= bedrock_names
|
||||
|
||||
|
||||
def _dockerfile_stages() -> dict[str, list[str]]:
|
||||
"""Map each Dockerfile stage to its instruction lines, parent stages first.
|
||||
|
||||
A stage that is ``FROM <earlier stage>`` inherits that stage's filesystem
|
||||
and metadata (VOLUME, WORKDIR, ARG-derived values), so the parent's lines
|
||||
are part of what the child ships.
|
||||
"""
|
||||
own: dict[str, list[str]] = {}
|
||||
parent: dict[str, str] = {}
|
||||
current: list[str] | None = None
|
||||
for raw in (ROOT / "Dockerfile").read_text(encoding="utf-8").splitlines():
|
||||
line = raw.strip()
|
||||
from_match = re.match(r"FROM\s+(\S+)\s+AS\s+(\S+)$", line, re.IGNORECASE)
|
||||
if from_match:
|
||||
base, name = from_match.groups()
|
||||
current = own.setdefault(name, [])
|
||||
if base in own:
|
||||
parent[name] = base
|
||||
elif current is not None and line and not line.startswith("#"):
|
||||
current.append(line)
|
||||
stages: dict[str, list[str]] = {}
|
||||
for name in own:
|
||||
chain, node = [], name
|
||||
while node:
|
||||
chain.insert(0, node)
|
||||
node = parent.get(node, "")
|
||||
stages[name] = [line for stage in chain for line in own[stage]]
|
||||
return stages
|
||||
|
||||
|
||||
def test_docker_bake_runtime_args_are_declared_by_the_selected_stage() -> None:
|
||||
"""Each bake target's runtime args must reach the stage it builds (#4443).
|
||||
|
||||
Build args are scoped to one Dockerfile stage, so passing ``RUNTIME_HOME``
|
||||
to a target whose ``target =`` stage has no ``ARG RUNTIME_HOME`` is a
|
||||
silent no-op. The distroless ``runtime-slim`` stage once ignored it, so the
|
||||
slim root variants shipped without the state volume.
|
||||
"""
|
||||
stages = _dockerfile_stages()
|
||||
bake = (ROOT / "docker-bake.hcl").read_text(encoding="utf-8")
|
||||
blocks = re.findall(r'^target "([^"]+)" \{\n(.*?)^\}', bake, flags=re.S | re.M)
|
||||
checked = {}
|
||||
for name, body in blocks:
|
||||
stage_match = re.search(r'^\s*target\s*=\s*"([^"]+)"', body, re.M)
|
||||
if not stage_match:
|
||||
continue
|
||||
stage = stage_match.group(1)
|
||||
assert stage in stages, f"{name} selects unknown Dockerfile stage {stage}"
|
||||
declared = {m.group(1) for line in stages[stage] if (m := re.match(r"ARG\s+(\w+)", line))}
|
||||
passed = set(re.findall(r"^\s*(RUNTIME_\w+)\s*=", body, re.M))
|
||||
assert passed <= declared, f"{name}: stage {stage} does not declare {passed - declared}"
|
||||
home = re.search(r'RUNTIME_HOME\s*=\s*"([^"]+)"', body)
|
||||
user = re.search(r'RUNTIME_USER\s*=\s*"([^"]+)"', body)
|
||||
if user and user.group(1) == "root":
|
||||
assert home and home.group(1) == "/root", f"{name}: root target needs /root"
|
||||
if home:
|
||||
# The stage must put its state volume under the home it was given.
|
||||
assert "VOLUME ${RUNTIME_HOME}/.headroom" in stages[stage], f"{name}: {stage}"
|
||||
checked[name] = stage
|
||||
assert {"runtime", "runtime-code", "runtime-slim", "runtime-code-slim"} <= set(checked)
|
||||
assert {checked[n] for n in ("runtime-slim", "runtime-code-slim")} == {"runtime-slim"}
|
||||
|
||||
|
||||
def test_every_docker_variant_includes_the_redis_extra() -> None:
|
||||
"""Without the client, HEADROOM_COMPRESS_SESSION_STORE=redis:// stops
|
||||
startup and HEADROOM_CCR_BACKEND=redis falls back to a per-process store,
|
||||
|
||||
Reference in New Issue
Block a user