mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
## Description With the `persistent-docker` preset, Kompress never loads. The container runs as the host user (`--user 501:20`) with `HOME=/tmp/headroom-home`, but the image never creates that directory. Docker creates it as `root:root 0755` to hold the bind mounts, so the proxy cannot create `~/.cache` and the HuggingFace download of the Kompress model fails with `Permission denied (os error 13)`. The log never shows that error: it reports a missing dependency instead (`Kompress requires onnxruntime or torch`), pointing the operator at reinstalling extras that are already present. Fix: point `HF_HOME` and `XDG_CACHE_HOME` at the bind-mounted, host-owned `.headroom` workspace so the cache is writable regardless of who Docker made the container's `$HOME`; and keep the underlying `OSError` in both `kompress_compressor.py` log sites instead of masking it. Closes #4207 ## 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 - `headroom/install/runtime.py`: `build_runtime_command()` now emits `HF_HOME` and `XDG_CACHE_HOME` as real `--env` flags pointing under the bind-mounted `.headroom` workspace (`<container_home>/.headroom/cache`), and applies them to the persistent-container args path, not only the dev/foreground path. - `headroom/install/runtime.py`: added `_append_cache_env()` and wired it through both command builders. - `scripts/install.sh` and `docker/docker-compose.native.yml`: set `HF_HOME`/`XDG_CACHE_HOME` under the writable `.headroom` mount for the same preset. - `headroom/transforms/kompress_compressor.py`: `_create_onnx_session()` appends the underlying cause to its `No loadable ONNX artifact` message; `_load_kompress()` re-raises the real ONNX failure (chained) instead of reporting a missing dependency when onnxruntime is present but loading failed. ## Testing - [x] Unit tests pass (`pytest`) - [ ] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text $ .venv/bin/python -m pytest tests/test_install/ tests/test_kompress_failsafe.py -q 278 passed, 11 skipped, 1 failed The single failure is tests/test_install/test_runtime.py::test_build_runtime_command_lets_the_host_dashboard_read_its_data which fails with ImportError: FastAPI required in this environment. It fails identically on unmodified main here, so it is a local environment gap, not this change. New regression tests, all passing: - test_build_runtime_command_keeps_hf_cache_on_the_writable_mount - test_build_runtime_command_persistent_path_keeps_hf_cache_on_the_writable_mount - test_no_loadable_artifact_message_carries_the_underlying_error - test_onnx_failure_while_onnxruntime_available_reports_the_real_error - test_missing_dependency_still_reports_install_hint $ bash -n scripts/install.sh # clean $ python -c "import yaml,sys;yaml.safe_load(open('docker/docker-compose.native.yml'))" # clean ``` ## Real Behavior Proof - Environment: Linux, Python venv at `.venv`, repo at this branch. No Docker daemon available on this machine. - Exact command / steps: `pytest tests/test_install/ tests/test_kompress_failsafe.py -q`; asserted the generated `docker run` argv from both `build_runtime_command()` and `build_persistent_container_args()` contains `--env HF_HOME` / `--env XDG_CACHE_HOME` pointing under the `.headroom` mount. - Observed result: all new tests pass; both argv builders now emit the cache env pointing at the writable host-owned mount. - Not tested: the end-to-end container run from the issue's reproduction steps — no Docker daemon here. The fix is verified at the level of the generated `docker run` argv and the unit tests above. ## Runtime Rollout Safety - Rollout-managed feature(s): Kompress proxy model loading under the `persistent-docker` preset. - Minimum rollout channel: all channels that use the persistent-docker preset; the change only affects env vars for cache directories. - Stable/default behavior changed: no. Default (non-persistent) paths are unchanged; persistent paths gain two `--env` flags pointing at an existing writable mount. - Kill switch / disable path: unset/override `HF_HOME`/`XDG_CACHE_HOME`, or run without the persistent-docker preset. - Unsafe override required: no. - Qualification impact: none. - Rollback path: revert this commit; the preset returns to the previous (broken) cache behavior. ## 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) ## Additional Notes - Docs untouched: no user-facing docs describe `HF_HOME`/`XDG_CACHE_HOME` for this preset, so no documentation change was needed (hence the unchecked box). - No lint/type-check run: `ruff`/`mypy` are not installed in this environment. - No Docker daemon available, so the container-level e2e reproduction was not executed — flagged under "Not tested" above. --------- Co-authored-by: Shivam Maurya <shivam@programmingwithmaurya.com> Co-authored-by: JD Davis <mxjerrett@gmail.com> Co-authored-by: JerrettDavis <jerrett@headroomlabs.ai>
59 lines
3.0 KiB
YAML
59 lines
3.0 KiB
YAML
services:
|
|
cli:
|
|
image: ${HEADROOM_IMAGE:-ghcr.io/headroomlabs-ai/headroom:latest}
|
|
entrypoint: ["headroom"]
|
|
working_dir: /workspace
|
|
stdin_open: true
|
|
tty: true
|
|
environment:
|
|
HOME: /tmp/headroom-home
|
|
# Docker creates /tmp/headroom-home as root:root, so $HOME is not
|
|
# writable by the --user the container runs as (issue #4207). Keep the
|
|
# HuggingFace/XDG caches on the bind-mounted workspace instead.
|
|
HF_HOME: /tmp/headroom-home/.headroom/cache/huggingface
|
|
XDG_CACHE_HOME: /tmp/headroom-home/.headroom/cache
|
|
# Canonical Headroom filesystem contract (issue #175). Forwarded into
|
|
# the container so the proxy resolves state/config to the bind-mounted
|
|
# /tmp/headroom-home/.headroom path. HEADROOM_WORKSPACE (above) remains
|
|
# the Docker bind-mount source and is intentionally different.
|
|
HEADROOM_WORKSPACE_DIR: /tmp/headroom-home/.headroom
|
|
HEADROOM_CONFIG_DIR: /tmp/headroom-home/.headroom/config
|
|
volumes:
|
|
- ${HEADROOM_WORKSPACE:-.}:/workspace
|
|
- ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.headroom:/tmp/headroom-home/.headroom
|
|
- ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.claude:/tmp/headroom-home/.claude
|
|
- ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.codex:/tmp/headroom-home/.codex
|
|
- ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.gemini:/tmp/headroom-home/.gemini
|
|
command: ["--help"]
|
|
|
|
proxy:
|
|
image: ${HEADROOM_IMAGE:-ghcr.io/headroomlabs-ai/headroom:latest}
|
|
entrypoint: ["headroom", "proxy"]
|
|
working_dir: /workspace
|
|
restart: unless-stopped
|
|
environment:
|
|
HOME: /tmp/headroom-home
|
|
# See the `cli` service above (issue #4207).
|
|
HF_HOME: /tmp/headroom-home/.headroom/cache/huggingface
|
|
XDG_CACHE_HOME: /tmp/headroom-home/.headroom/cache
|
|
HEADROOM_HOST: 0.0.0.0
|
|
HEADROOM_PROXY_TOKEN: ${HEADROOM_PROXY_TOKEN:-}
|
|
# The container binds 0.0.0.0 so the loopback publication below can reach
|
|
# it; the proxy refuses that bind without a token unless the operator
|
|
# acknowledges it. This file always publishes on 127.0.0.1, so it does.
|
|
# Irrelevant (and harmless) once HEADROOM_PROXY_TOKEN is set.
|
|
HEADROOM_ALLOW_UNAUTHENTICATED_BIND: "1"
|
|
# Canonical Headroom filesystem contract (issue #175). See `cli` service
|
|
# above for rationale.
|
|
HEADROOM_WORKSPACE_DIR: /tmp/headroom-home/.headroom
|
|
HEADROOM_CONFIG_DIR: /tmp/headroom-home/.headroom/config
|
|
ports:
|
|
- "127.0.0.1:${HEADROOM_PORT:-8787}:${HEADROOM_PORT:-8787}"
|
|
volumes:
|
|
- ${HEADROOM_WORKSPACE:-.}:/workspace
|
|
- ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.headroom:/tmp/headroom-home/.headroom
|
|
- ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.claude:/tmp/headroom-home/.claude
|
|
- ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.codex:/tmp/headroom-home/.codex
|
|
- ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.gemini:/tmp/headroom-home/.gemini
|
|
command: ["--host", "0.0.0.0", "--port", "${HEADROOM_PORT:-8787}"]
|