akadmin/headroom
1
0
Fork 0
mirror of https://github.com/headroomlabs-ai/headroom.git synced 2026-08-27 14:17:10 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

fix(docs): fix Docker example and document hnswlib C++ build requirement

Browse source 
The Docker example in proxy.md used the wrong package name and lacked
build-essential, causing install failures on slim images. hnswlib (a
core dependency) requires a C++ compiler to build from source.

- Fix proxy.md Docker example: headroom[proxy] -> headroom-ai[proxy],
  add build-essential install/cleanup pattern
- Add troubleshooting entry for C++ compilation errors with solutions
  for Linux and macOS environments

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Long Ngo 2026-03-02 14:46:14 -06:00
parent ae661c8a2e
commit 693deb4d58
2 changed files with 39 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

7
docs/proxy.md
View file

@ -248,7 +248,12 @@ Or with Docker:
```dockerfile
FROM python:3.11-slim
RUN pip install headroom[proxy]
RUN apt-get update && apt-get install -y --no-install-recommends build-essential \
&& pip install "headroom-ai[proxy]" \
&& apt-get purge -y build-essential && apt-get autoremove -y \
&& rm -rf /var/lib/apt/lists/*
EXPOSE 8787
CMD ["headroom", "proxy", "--host", "0.0.0.0"]
```
> **Note:** `build-essential` is required at install time because `headroom-ai` includes `hnswlib`, a C++ extension that must be compiled from source. It is removed after installation to keep the image slim.

33
docs/troubleshooting.md
View file

@ -219,6 +219,39 @@ client = HeadroomClient(
## Import/Installation Issues
### "pip install fails with C++ compilation error"
**Symptom**: Installation fails with an error like:
```
RuntimeError: Unsupported compiler -- at least C++11 support is needed!
ERROR: Failed building wheel for hnswlib
```
**Cause**: `headroom-ai` depends on `hnswlib`, a C++ extension that must be compiled from source. Slim environments (Docker slim images, minimal CI runners) lack the required build tools.
**Solutions**:
```bash
# Linux / Debian-based (including Docker)
apt-get install -y build-essential && pip install headroom-ai
# macOS (Xcode command line tools)
xcode-select --install && pip install headroom-ai
```
In a Dockerfile, install and remove build tools in one layer to keep the image slim:
```dockerfile
FROM python:3.11-slim
RUN apt-get update && apt-get install -y --no-install-recommends build-essential \
&& pip install "headroom-ai[proxy]" \
&& apt-get purge -y build-essential && apt-get autoremove -y \
&& rm -rf /var/lib/apt/lists/*
```
---
### "ModuleNotFoundError: No module named 'headroom'"
```bash