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            # head 59bd12d
58 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 on ae30825 (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:
Younes Beriane
2026-11-03 22:49:38 -06:00
committed by GitHub
co-authored by JD Davis
parent 6ef52c2047
commit 670767eeb4
3 changed files with 80 additions and 0 deletions
+13
View File
@@ -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}.
+4
View File
@@ -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"
}
}
+63
View File
@@ -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,