caddy-docker-proxy: Route Docker Traffic Through Caddy

Overview

caddy-docker-proxy connects Docker metadata to Caddy: it reads labels on containers or services, generates Caddy configuration, and reloads Caddy when Docker objects change. This reduces the manual work of keeping proxy routes in sync with deployed workloads.

It is aimed at people already running Docker who want Caddy to route traffic to changing containers or Swarm services. Labels support both straightforward host-to-service routing and more customized Caddy directives. The project can run as a standalone proxy or split controller and server roles across a cluster.

Key Features

• Builds Caddy site configuration from Docker labels, including nested directives and snippets.
• Updates configuration in response to Docker changes and triggers graceful Caddy reloads.
• Provides an upstreams template function to select Docker service or container addresses.
• Supports routing to containers and Swarm services, with configurable service-task proxying.
• Offers standalone, controller, and server execution modes for different deployment layouts.
• Supports a base Caddyfile, Docker configs for Swarm, and environment or CLI configuration options.
• Works with Caddy's automatic HTTPS when domains and deployment conditions allow it.

Use Cases

• A self-hosting administrator can add a proxy route by labeling a new Compose service instead of editing a central Caddyfile.
• A Docker Swarm operator can generate routes from service labels and distribute configuration through controller and server instances.
• A team running multiple internal web services can route different hostnames or paths to their corresponding containers.
• A Caddy user can keep custom Caddy directives while using Docker labels for routes that change with deployments.

Project Facts

• Language: Go
• License: MIT
• Stars: 4.7k
• Forks: 224
• Archived: false

Getting Started

Create a Docker network for Caddy, then run the proxy with access to the Docker socket:

docker network create caddy --ipv6
docker run --name caddy -d -p 80:80 -p 443:443 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  lucaslorentz/caddy-docker-proxy:ci-alpine

Add caddy labels to a container or service to define its site and proxy target. See the README for Compose and Swarm examples, image choices, and configuration details.

Alternatives

• NPMplus: NPMplus manages proxy hosts through a web interface and a hardened Nginx build, rather than generating Caddy configuration from Docker labels.
• openresty-manager: OpenResty Manager uses a web control panel to manage OpenResty hosts, certificates, and containers instead of deriving routes from Docker labels.
• netgoat: NetGoat is a standalone reverse proxy with authentication, caching, and rate-limit controls, rather than a Docker-label-driven Caddy configuration generator.
• wiredoor: Wiredoor provides ingress through WireGuard tunnels and supports TCP and UDP, while caddy-docker-proxy configures Caddy routes from Docker labels.

Considerations

• The controller needs access to the Docker host socket. Treat that access as sensitive and account for it in your deployment's security design.
• Correct upstream discovery depends on Docker network configuration. The README recommends setting ingress networks explicitly in cases where automatic detection is unreliable.
• Persistent storage for Caddy's /data directory is important in production so restarts do not repeatedly issue certificates.
• The README identifies CI-tagged images as reflecting the current master branch, with stability not guaranteed. Prefer a fixed release image for deployments that need predictable versions.
• The README describes Windows container images as experimental.