Files
headroom/docker-bake.hcl
Younes BerianeandJD Davis 670767eeb4 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>
2026-11-03 22:49:38 -06:00

93 lines
2.0 KiB
HCL

target "docker-metadata-action" {}
target "_common" {
context = "."
dockerfile = "Dockerfile"
platforms = ["linux/amd64", "linux/arm64"]
}
target "runtime-default" {
inherits = ["_common", "docker-metadata-action"]
target = "runtime"
args = {
HEADROOM_EXTRAS = "proxy,bedrock,redis"
RUNTIME_USER = "nonroot"
}
}
target "runtime" {
inherits = ["_common", "docker-metadata-action"]
target = "runtime"
args = {
HEADROOM_EXTRAS = "proxy,bedrock,redis"
RUNTIME_USER = "root"
RUNTIME_HOME = "/root"
}
}
target "runtime-nonroot" {
inherits = ["_common", "docker-metadata-action"]
target = "runtime"
args = {
HEADROOM_EXTRAS = "proxy,bedrock,redis"
RUNTIME_USER = "nonroot"
}
}
target "runtime-code" {
inherits = ["_common", "docker-metadata-action"]
target = "runtime"
args = {
HEADROOM_EXTRAS = "proxy,code,bedrock,redis"
RUNTIME_USER = "root"
RUNTIME_HOME = "/root"
}
}
target "runtime-code-nonroot" {
inherits = ["_common", "docker-metadata-action"]
target = "runtime"
args = {
HEADROOM_EXTRAS = "proxy,code,bedrock,redis"
RUNTIME_USER = "nonroot"
}
}
target "runtime-slim" {
inherits = ["_common", "docker-metadata-action"]
target = "runtime-slim"
args = {
HEADROOM_EXTRAS = "proxy,bedrock,redis"
RUNTIME_USER = "root"
RUNTIME_HOME = "/root"
}
}
target "runtime-slim-nonroot" {
inherits = ["_common", "docker-metadata-action"]
target = "runtime-slim"
args = {
HEADROOM_EXTRAS = "proxy,bedrock,redis"
RUNTIME_USER = "nonroot"
}
}
target "runtime-code-slim" {
inherits = ["_common", "docker-metadata-action"]
target = "runtime-slim"
args = {
HEADROOM_EXTRAS = "proxy,code,bedrock,redis"
RUNTIME_USER = "root"
RUNTIME_HOME = "/root"
}
}
target "runtime-code-slim-nonroot" {
inherits = ["_common", "docker-metadata-action"]
target = "runtime-slim"
args = {
HEADROOM_EXTRAS = "proxy,code,bedrock,redis"
RUNTIME_USER = "nonroot"
}
}