# 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=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*