docker-easy-haproxy/docs/getting-started/docker.md

sidebar_position	sidebar_label
3	Docker

Docker

EasyHAProxy inspects running Docker containers, reads their labels, and configures HAProxy automatically.

:::warning Limitations

• You cannot mix Docker containers with Swarm containers.
• EasyHAProxy itself cannot run with the --network=host option. See limitations for details. :::

Step 1 — Create a shared network

docker network create easyhaproxy

It's recommended to use an external network so EasyHAProxy and your app containers can communicate.

Step 2 — Run EasyHAProxy

docker run -d \
      --name easy-haproxy-container \
      -v /var/run/docker.sock:/var/run/docker.sock \
      -e EASYHAPROXY_DISCOVER="docker" \
      -p 80:80 \
      -p 443:443 \
      -p 1936:1936 \
      --network easyhaproxy \
    byjg/easy-haproxy

Mounting /var/run/docker.sock is required so EasyHAProxy can query the Docker API.

Step 3 — Label your container

docker run -d \
      --label easyhaproxy.http.host=example.org \
      --label easyhaproxy.http.port=80 \
      --label easyhaproxy.http.localport=8080 \
      --network easyhaproxy \
    my/image:tag

EasyHAProxy detects this container automatically and routes traffic from example.org:80 to port 8080 in your container. You do not need to expose any container ports.

Containers using --network=host

Containers that share the host network namespace (--network=host, or network_mode: host in Compose) cannot join the EasyHAProxy network, so EasyHAProxy reaches them through the gateway of its own network instead. Label them as usual, but set localport to the port the service binds on the host:

services:
  myapp:
    image: my/image:tag
    network_mode: host
    labels:
      easyhaproxy.myapp.host: example.org
      easyhaproxy.myapp.port: 80
      easyhaproxy.myapp.localport: 8080   # the port on the host

The same applies to containers sharing another container's namespace (network_mode: "container:xxx", as used by VPN sidecars); those are reached at the address of the container owning the namespace.

The service must bind 0.0.0.0 rather than 127.0.0.1, otherwise it is unreachable from the EasyHAProxy container. If your host firewall blocks the Docker bridge, or the detected gateway is not the address you want, override it with EASYHAPROXY_HOST_NETWORK_IP.

Step 4 — Verify

Open http://example.org in your browser (or curl http://example.org). Traffic should reach your container.

---

Full options

• Container label reference — all available labels
• Environment variable reference — configure EasyHAProxy behavior
• SSL certificates — add custom TLS
• ACME / Let's Encrypt — automatic certificate issuing

---

Open source ByJG