Quickstart

1. Dry run — no credentials needed

DockRoute defaults to the log provider, which runs the whole pipeline and prints the desired state it computes instead of touching a zone. It is the safest way to check your labels.

services:
  whoami:
    image: traefik/whoami
    labels:
      dockroute.enabled: "true"
      dockroute.hostname: "whoami.example.com"

  dockroute:
    image: ghcr.io/dockroute/dockroute:latest
    environment:
      DOCKROUTE_DEFAULT_TARGET: 192.168.1.10
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    group_add:
      - "990" # the host's docker group — see note below

docker compose up

You should see the desired state logged: an A record for whoami.example.com pointing at 192.168.1.10.

stat -c '%g' /var/run/docker.sock

2. Go live with Cloudflare

Switch the provider and add a token with Zone → Zone → Read and Zone → DNS → Edit permissions:

  dockroute:
    image: ghcr.io/dockroute/dockroute:latest
    environment:
      DOCKROUTE_PROVIDER: cloudflare
      DOCKROUTE_OWNER_ID: home-lab
      DOCKROUTE_DEFAULT_TARGET: 192.168.1.10
      CLOUDFLARE_API_TOKEN: ${CLOUDFLARE_API_TOKEN}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    group_add:
      - "990"

Restart the stack. DockRoute lists your running containers, computes the desired records and reconciles them. From now on, every container start and stop triggers a reconcile, and a full resync runs every 60 seconds.

3. Publish through a Cloudflare Tunnel (optional)

If you already run cloudflared with a tunnel, one extra label publishes a service through it — no port forwarding at all:

  whoami:
    image: traefik/whoami
    labels:
      dockroute.enabled: "true"
      dockroute.hostname: "whoami.example.com"
      dockroute.tunnel.service: "http://whoami:80"

The tunnel needs two more environment variables on the DockRoute container (CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_TUNNEL_ID) and the token needs Account → Cloudflare Tunnel → Edit. See the Cloudflare Tunnel guide for the full setup.

Verify

• docker compose logs dockroute shows every create, update, delete and skipped conflict.
• Your zone now contains the record and a companion TXT like _dockroute-a.whoami.example.com — that TXT is DockRoute's proof of ownership.
• Stop the whoami container: under the default sync policy both records are removed on the next reconcile.