09-docker-proxy.md
kstack: book: Centerpoint Home Lab chapter: Utilities page: Docker Socket Proxy tags: [dockerproxy, security, docker, infrastructure]
Overview
emptyThe 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)
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
/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
CONTAINERS=1 and EVENTS=1 means 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
dockerproxy is running and on the same Docker network as Homepage.
The tecnativa/docker-socket-proxy image 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