09-docker-proxy.md
kstack: book: Centerpoint Home Lab chapter: Utilities page: Docker Socket Proxy tags: [dockerproxy, security, docker, infrastructure]
Overview
The Docker Socket Proxy (dockerproxy) provides a read-only, filtered proxy to
the Docker daemon socket. It exposes a limited subset of the Docker API over TCP,
allowing containers like Homepage to query running container data without
requiring direct access to /var/run/docker.sock. No Traefik route — internal
use only.
Configuration
Image: tecnativa/docker-socket-proxy
Environment Variables (API Permission Flags)
| Variable | Value | Permission granted |
|---|---|---|
CONTAINERS |
1 |
Read container list and inspect data |
EVENTS |
1 |
Subscribe to Docker events stream |
POST |
0 |
Disabled — no write operations |
ALLOW_START |
0 |
Cannot start containers |
ALLOW_STOP |
0 |
Cannot stop containers |
ALLOW_RESTARTS |
0 |
Cannot restart containers |
AUTH |
0 |
No auth endpoint access |
BUILD |
0 |
No build operations |
COMMIT |
0 |
No commit operations |
CONFIGS |
0 |
No config access |
DISTRIBUTION |
0 |
No distribution endpoint access |
All write operations are disabled. The proxy grants read-only container metadata access only.
Volumes / Bind Mounts
| Host Path | Container Path | Purpose |
|---|---|---|
/var/run/docker.sock |
/var/run/docker.sock |
Docker socket (read-only proxy source) |
Consumer
The primary consumer is Homepage (homepage.home.local), which connects to
dockerproxy:2375 to discover running containers and display live service
status widgets. This avoids mounting the Docker socket directly into Homepage.
Notes / Gotchas
- The proxy listens on TCP port 2375 (standard Docker API port) inside the Docker network — it is not exposed on any host port or Traefik route.
- Allowing only
CONTAINERS=1andEVENTS=1means Homepage can list containers and receive real-time status events, but cannot perform any management actions. - If Homepage shows containers as offline or fails to discover services, verify
dockerproxyis running and on the same Docker network as Homepage. - The
tecnativa/docker-socket-proxyimage is the community standard for this pattern. It is based on HAProxy 3.x and routes allowed API paths only.
Last Updated: 2026-06-17