mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-27 14:17:10 -04:00
fix(docker): publish compose ports on loopback only (#3061)
## Description `docker compose up -d` published every service on `0.0.0.0`, and none of the three authenticates an inbound caller by default: | port | service | default auth | |---|---|---| | 8787 | proxy | `/v1/*` data plane open unless `HEADROOM_PROXY_TOKEN` is set | | 6333/6334 | Qdrant | **none at all** — holds embeddings derived from prompts | | 7474/7687 | Neo4j | `NEO4J_AUTH` falls back to `neo4j/devpassword`, published in this file | So the shipped default handed any peer on the surrounding network a relay through the proxy plus direct read/write on the vector and graph stores built from the operator's own prompt content. The proxy already warns about exactly this shape at `headroom/proxy/server.py:3289` — the compose file just never took its own advice. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [x] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update ## Changes Made - Pinned all five published ports to `127.0.0.1`. - Documented in the file header how to expose the proxy deliberately, pairing the port override with `HEADROOM_PROXY_TOKEN` rather than leaving that implicit. - Added a commented `HEADROOM_PROXY_TOKEN` entry to the proxy service environment. - Added a regression test asserting every published port names a loopback host IP. ## Testing - [x] Unit tests pass - [x] Linting passes (ruff check + format) - [ ] Type checking passes — N/A (YAML + test only) - [x] New tests added for new functionality ### Test Output ```text $ .venv/bin/python -m pytest tests/test_docker_compose_persistence.py -q 3 passed in 0.14s $ docker compose -f docker-compose.yml config # validates headroom-proxy host_ip=127.0.0.1 published=8787 -> 8787 neo4j host_ip=127.0.0.1 published=7474 -> 7474 neo4j host_ip=127.0.0.1 published=7687 -> 7687 qdrant host_ip=127.0.0.1 published=6333 -> 6333 qdrant host_ip=127.0.0.1 published=6334 -> 6334 ``` Against the parent commit: ```text FAILED test_top_level_compose_publishes_only_to_loopback E AssertionError: headroom-proxy: port '8787:8787' publishes on all interfaces ``` ## Real Behavior Proof - Environment: macOS 15 (darwin 25.4.0), Docker Compose v2 available locally. - Exact command / steps: `docker compose -f docker-compose.yml config --format json` before and after, comparing the resolved `host_ip` on every published port. - Observed result: before, no port carried a `host_ip` (Docker binds `0.0.0.0`); after, all five resolve to `host_ip=127.0.0.1`. The compose file still validates. - Not tested: bringing the stack up and probing the ports from a second machine on the LAN — the assertion is made against Docker's own resolved configuration rather than a live two-host network. ## Runtime Rollout Safety - Rollout-managed feature(s): none. - Minimum rollout channel: N/A. - Stable/default behavior changed: yes — the compose stack is no longer reachable from other machines by default. - Kill switch / disable path: override `ports:` in a `docker-compose.override.yml`; the header documents this and pairs it with `HEADROOM_PROXY_TOKEN`. - Unsafe override required: none. - Qualification impact: none. - Rollback path: revert this commit. ## 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 - [x] I have made corresponding changes to the documentation (the compose header) - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective - [x] New and existing unit tests pass locally with my changes ## Additional Notes **This is a deliberate breaking change for one workflow**: anyone reaching the compose proxy from another machine will need to override `ports:`. That is exactly the configuration that was unsafe, so it should break loudly rather than silently. `http://localhost:8787` from the host is unchanged, the container still listens on `0.0.0.0` internally, and service-to-service traffic on the compose network is unaffected. Scope note: I fixed all three services rather than only the proxy. Closing 8787 while leaving an unauthenticated Qdrant and a default-password Neo4j published on `0.0.0.0` would not have improved the security posture. Co-authored-by: Tejas Chopra <tejas@Tejass-MacBook-Pro.local>
This commit is contained in:
Tejas Chopra
GitHub
parent
a6ab359a5d
commit
481e0b83d5
2 changed files with 60 additions and 6 deletions
|
|
@ -13,10 +13,23 @@
|
|||
# on its own (`docker run -p 8787:8787 ghcr.io/headroomlabs-ai/headroom`); the two
|
||||
# database services below are only required for the memory/relevance features.
|
||||
#
|
||||
# Ports exposed on the host:
|
||||
# Ports published on the host — all bound to 127.0.0.1 (this machine only):
|
||||
# 8787 proxy (OpenAI-compatible endpoint)
|
||||
# 6333 Qdrant REST 6334 Qdrant gRPC
|
||||
# 7474 Neo4j Browser 7687 Neo4j Bolt
|
||||
#
|
||||
# None of these three services authenticates inbound callers by default: the
|
||||
# proxy's /v1/* data plane is open unless HEADROOM_PROXY_TOKEN is set, Qdrant
|
||||
# has no API key, and Neo4j falls back to a published dev password. Publishing
|
||||
# them on 0.0.0.0 therefore hands any peer on your network a relay through the
|
||||
# proxy plus direct read/write on the embeddings and graph derived from your
|
||||
# prompts. They are bound to loopback so that `docker compose up -d` is safe on
|
||||
# a shared or untrusted network.
|
||||
#
|
||||
# To reach the proxy from another machine, publish it deliberately AND require
|
||||
# a token — never one without the other:
|
||||
# HEADROOM_PROXY_TOKEN=$(openssl rand -hex 32) # put this in .env
|
||||
# ports: ["8787:8787"] # override in a compose override file
|
||||
# =============================================================================
|
||||
|
||||
services:
|
||||
|
|
@ -38,8 +51,14 @@ services:
|
|||
# if you want to use a custom OpenAI-compatible API endpoint,
|
||||
# uncomment and set the following line with the desired URL
|
||||
# - OPENAI_TARGET_API_URL=https://api.x.ai
|
||||
# Required before publishing this port beyond loopback: without it the
|
||||
# /v1/* data plane accepts unauthenticated callers.
|
||||
# - HEADROOM_PROXY_TOKEN=${HEADROOM_PROXY_TOKEN}
|
||||
ports:
|
||||
- "8787:8787"
|
||||
# Loopback-only. The container still listens on 0.0.0.0 (above) so the
|
||||
# other compose services can reach it by name; this line controls only
|
||||
# which host interfaces the port is published on.
|
||||
- "127.0.0.1:8787:8787"
|
||||
volumes:
|
||||
- headroom_workspace:/home/nonroot/.headroom
|
||||
# Readiness probe: the orchestrator polls /readyz so dependents and
|
||||
|
|
@ -62,8 +81,10 @@ services:
|
|||
qdrant:
|
||||
image: qdrant/qdrant:v1.17.1
|
||||
ports:
|
||||
- "6333:6333" # REST API
|
||||
- "6334:6334" # gRPC
|
||||
# Loopback-only: Qdrant runs unauthenticated here and holds embeddings
|
||||
# derived from your prompts.
|
||||
- "127.0.0.1:6333:6333" # REST API
|
||||
- "127.0.0.1:6334:6334" # gRPC
|
||||
# Named volume keeps the vector index across container restarts/recreates.
|
||||
volumes:
|
||||
- qdrant_data:/qdrant/storage
|
||||
|
|
@ -75,8 +96,10 @@ services:
|
|||
neo4j:
|
||||
image: neo4j:5.26
|
||||
ports:
|
||||
- "7474:7474" # HTTP (Browser)
|
||||
- "7687:7687" # Bolt
|
||||
# Loopback-only: NEO4J_AUTH below defaults to a password published in
|
||||
# this file, so an exposed Bolt port is an open database.
|
||||
- "127.0.0.1:7474:7474" # HTTP (Browser)
|
||||
- "127.0.0.1:7687:7687" # Bolt
|
||||
# Named volume persists the graph data across container restarts/recreates.
|
||||
volumes:
|
||||
- neo4j_data:/data
|
||||
|
|
|
|||
|
|
@ -4,9 +4,40 @@ from __future__ import annotations
|
|||
|
||||
from pathlib import Path
|
||||
|
||||
import yaml
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
|
||||
|
||||
def test_top_level_compose_publishes_only_to_loopback() -> None:
|
||||
"""Every published port must name an explicit loopback host IP.
|
||||
|
||||
None of the three services authenticates by default: the proxy's /v1/*
|
||||
data plane is open without HEADROOM_PROXY_TOKEN, Qdrant has no API key,
|
||||
and NEO4J_AUTH falls back to a password published in the compose file. A
|
||||
bare "8787:8787" binds 0.0.0.0 on the host, so `docker compose up -d` on a
|
||||
shared network would expose all three.
|
||||
"""
|
||||
compose = yaml.safe_load((ROOT / "docker-compose.yml").read_text(encoding="utf-8"))
|
||||
|
||||
published = [
|
||||
(service, port)
|
||||
for service, spec in compose["services"].items()
|
||||
for port in spec.get("ports", [])
|
||||
]
|
||||
assert published, "expected the compose file to publish at least one port"
|
||||
|
||||
for service, port in published:
|
||||
# Short syntax is "HOST_IP:HOST_PORT:CONTAINER_PORT"; anything with
|
||||
# fewer than three segments is published on every interface.
|
||||
assert isinstance(port, str), f"{service}: expected short-syntax port, got {port!r}"
|
||||
segments = port.split(":")
|
||||
assert len(segments) == 3, f"{service}: port {port!r} publishes on all interfaces"
|
||||
assert segments[0] in {"127.0.0.1", "::1"}, (
|
||||
f"{service}: port {port!r} publishes on {segments[0]}, not loopback"
|
||||
)
|
||||
|
||||
|
||||
def test_top_level_compose_pins_headroom_state_to_named_volume() -> None:
|
||||
compose = (ROOT / "docker-compose.yml").read_text(encoding="utf-8")
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue