Commit Graph
4 Commits
Author SHA1 Message Date
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
8d5dde7765 fix(docker): install the redis extra in every image (#4514)
## Description

The 0.42 images ship the replica-shared compress session store, but no
published variant installs the `redis` client. Setting
`HEADROOM_COMPRESS_SESSION_STORE=redis://...` stopped startup with
`ConfigurationError`, and `HEADROOM_CCR_BACKEND=redis` degraded to the
per-process store. This PR adds the `redis` extra to the Dockerfile
default and to all nine `docker-bake.hcl` targets. It locks the
invariant with a release test. It also documents the session fields of
`/v1/compress` and the shared session store.

Closes #4513

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (a fix or feature that changes existing
functionality)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `Dockerfile`, `docker-bake.hcl`: `HEADROOM_EXTRAS` gains `redis` in
the default and in all nine bake targets.
- `tests/test_release_workflows.py`: new
`test_every_docker_variant_includes_the_redis_extra` guards the
Dockerfile default, the bake targets, and the `pyproject.toml` extra.
- `docs/content/docs/installation.mdx`: new `redis` extras row. The
Docker tag table shows the new extras.
- `docs/content/docs/proxy.mdx`, `wiki/proxy.md`: documented the
`session` response fields, `HEADROOM_COMPRESS_SESSION_STORE`, its
failure behavior, and the `session_affinity` interaction.

## 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
$ python -m pytest tests/test_release_workflows.py -q
Pytest: 55 passed

$ uvx ruff@0.17.0 check .
All checks passed!
```

## Real Behavior Proof

- Environment: macOS worktree of this repository, Python 3.13.
- Exact command / steps: `python -m pytest
tests/test_release_workflows.py -q` and `uvx ruff@0.17.0 check .`.
- Observed result: 55 tests passed, ruff clean. The new test fails
against the pre-change `Dockerfile`, because its `ARG HEADROOM_EXTRAS`
line lacked `redis`.
- Not tested: the Docker images were not built. The release test asserts
the build args statically, as the sibling Bedrock test does.

## Runtime Rollout Safety

- Rollout-managed feature(s): none. The change touches build args, docs,
and a test.
- Minimum rollout channel: not applicable.
- Stable/default behavior changed: every published image now installs
the `redis` client. With the extra installed,
`HEADROOM_COMPRESS_SESSION_STORE=redis://...` starts instead of failing,
and `HEADROOM_CCR_BACKEND=redis` uses Redis instead of the per-process
fallback.
- Kill switch / disable path: drop `redis` from `HEADROOM_EXTRAS` at
build time, or unset the two environment variables at runtime.
- Unsafe override required: no.
- Qualification impact: none. No runtime code path changed. The `redis`
import stays lazy, so deployments that do not set the variables are
unaffected.
- Rollback path: revert this PR and rebuild.

## Review Readiness

- [x] I performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I performed a self-review of my code
- [x] I commented my code, particularly in hard-to-understand areas
- [x] I made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I 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, and a CI guard
enforces this.

## Screenshots (if applicable)

Not applicable.

## Additional Notes

The full test suite and `mypy headroom` were not run. This PR changes no
file under `headroom/`, so I ran the affected suite
(`tests/test_release_workflows.py`) and lint only. The docs half also
answers part of #3184 (documentation of the storage backends). The CI
half of #3184 stays open, and PR #3282 covers it.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4514"
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: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
Co-authored-by: Tejas Chopra <tejas@headroomlabs.ai>
2026-10-28 11:29:27 -07:00
JD Davis eafdf11a2c fix(docker): ship Bedrock auth and current registry (#2982)
## Description

Fixes #1551 and #1692.

Every published Headroom Docker image now installs the existing
`bedrock` extra, so `--backend bedrock` can authenticate with temporary
STS, SSO, and credential-process credentials instead of failing because
`botocore` is absent.

Public Docker instructions now consistently use
`ghcr.io/headroomlabs-ai/headroom`. Several still pointed at the old
personal package, which is frozen at 0.27.0 and caused users to report
that no latest image existed.

## Type of Change

- [x] Bug fix
- [ ] New feature
- [ ] Breaking change
- [x] Documentation update
- [x] Build / CI

## Changes Made

- Add `bedrock` to the standalone Dockerfile default extras.
- Add `bedrock` to all nine root/code/slim/nonroot bake targets.
- Replace obsolete personal GHCR references in README, llms.txt, Compose
guidance, testing guidance, and wiki docs.
- Add release contract tests for Bedrock dependencies and the current
organization registry.

## Testing

- [x] Focused Docker release and Bedrock preflight tests pass.
- [x] Full updater suites pass: 69 tests.
- [x] `uv run ruff check tests/test_release_workflows.py`
- [x] `docker buildx bake --print`
- [x] `git diff --check`

## Real Behavior Proof

Before this change, every published bake target installed only `proxy`
or `proxy,code`, so `AWS_SESSION_TOKEN` selected an unavailable botocore
path. Public copy-paste commands also referenced
`ghcr.io/chopratejas/headroom`, which the existing migration code and
changelog identify as frozen at 0.27.0.

After this change, all nine parsed bake targets install `bedrock`; the
regression resolves that package extra and confirms `boto3` plus
`botocore`. Every public Docker instruction covered by the contract
names `ghcr.io/headroomlabs-ai/headroom`.

## Runtime Rollout Safety

This changes image contents and documentation only; proxy routing and
non-Docker installs are unchanged. Static AWS credentials remain
unaffected. Existing manifests using the deprecated image continue to be
migrated by the established install-state logic. Rollback is a
Docker/bake extras and documentation revert.

## Review Readiness

- [x] Two related Docker blockers batched in one PR
- [x] Regression coverage included
- [x] No unrelated lockfile changes
- [x] Ready for review
2026-08-13 15:06:21 -05:00
pratikbin 63aebe8235 refactor(docker): migrate to bake with multi-variant distroless images 2026-04-04 21:51:37 +05:30