Docker / Swarm provider

Two providers in one package: standalone Docker (single-host or Compose) and Swarm mode. Both speak the Docker Engine API and read container labels to build routers, services, and middlewares.

Source

pkg/provider/docker/:

File	Role
pdocker.go	Standalone Docker provider.
pswarm.go	Swarm-mode provider.
config.go	Translation from labels to dynamic configuration.
data.go	Container/service/network data structures returned by the API.
shared.go	Code shared between the two providers.
shared_labels.go	Label names and parsing helpers.
builder_test.go	Test scaffolding for fixture-driven config tests.

Configuration

providers:
  docker:
    endpoint: unix:///var/run/docker.sock
    exposedByDefault: false
    network: web
    defaultRule: 'Host(`{{ .Name }}.docker.localhost`)'

  # or, for Swarm:
  swarm:
    endpoint: tcp://127.0.0.1:2377
    exposedByDefault: false
    refreshSeconds: 15

exposedByDefault: false is the recommended setting. With it, only containers/services labeled traefik.enable=true are picked up.

How labels become configuration

Docker labels follow this shape:

traefik.enable=true
traefik.http.routers.api.rule=Host(`api.example.com`)
traefik.http.routers.api.service=api
traefik.http.routers.api.middlewares=auth@docker
traefik.http.services.api.loadbalancer.server.port=8080
traefik.http.middlewares.auth.basicauth.users=admin:$apr1$...

pkg/provider/docker/config.go walks each container's labels and assembles the corresponding routers, services, middlewares, and TLS options. The resulting dynamic.Configuration carries only the objects discovered from this provider; the watcher merges them with other providers' contributions.

Discovery loop

For standalone Docker:

1. Connect to the Docker socket / TCP endpoint.
2. List existing containers, build configuration, emit a message.
3. Subscribe to the events API.
4. On any container start, die, health_status, update event, refresh.

For Swarm:

1. List services and tasks.
2. Refresh on a fixed interval (refreshSeconds, default 15s) — Swarm has no event stream.
3. Reconnect with backoff on transport errors.

graph TD
    Conf[Static config] --> Init
    Init -->|connect| API[Docker Engine API]
    API -->|containers/services| Build[config.go: build dynamic.Configuration]
    Build --> Send[send dynamic.Message]
    API -->|events / poll| Build

Network selection

The network field tells the provider which Docker network to use when picking the container's IP. Without it, the provider uses the first network in alphabetical order. Mis-set network selection is a top source of "why is my container not reachable" support tickets.

If a service exposes multiple ports, label traefik.http.services.X.loadbalancer.server.port=PORT disambiguates.

Constraints

providers:
  docker:
    constraints: 'Label(`environment`, `production`)'

The constraint expression is evaluated by pkg/provider/constraints/ and filters which containers participate. Useful for sharing one Docker daemon across multiple Traefik instances.

TLS to the Docker API

When the endpoint is TCP and TLS-protected, configure cert/key/CA via the tls block. The provider also honors DOCKER_* environment variables when present (compatibility with docker CLI conventions).

Tests

• pkg/provider/docker/config_test.go — table-driven mapping from labels to dynamic configuration.
• pkg/provider/docker/pswarm_test.go — Swarm task discovery using pswarm_mock_test.go mocks.
• integration/docker_test.go — end-to-end against a real Docker daemon.
• integration/docker_compose_test.go — Compose stacks.

Practical tips

• For Compose: use traefik.enable=true only on the services you intend to expose.
• The default rule template is your friend — set defaultRule: 'Host({{ .Name }}.example.com)' and you can drop most label boilerplate.
• The provider does not know about user-defined networks unless the Traefik container is attached to them. docker run --network web (or its Compose equivalent) is mandatory.

For container orchestrators that aren't Swarm, see Kubernetes, Nomad, ECS, or Consul Catalog.