dockroute

External-DNS for plain Docker hosts: dockroute watches your running containers, reads dockroute.* labels and reconciles the matching DNS records — and Cloudflare Tunnel routes — in a pluggable provider.

Your Docker Compose file is the source of truth; dockroute makes the provider match it, and never alters what it cannot prove it manages (ExternalDNS-style TXT ownership).

Status: MVP + Cloudflare. DNS records, TXT ownership, sync policies and Cloudflare Tunnel routes work end to end. See ARCHITECTURE.md.

Quick start

Label a container:

services:
  whoami:
    image: traefik/whoami
    labels:
      dockroute.enabled: "true"
      dockroute.hostname: "whoami.example.com"
      # publish through an existing Cloudflare Tunnel:
      dockroute.tunnel.service: "http://whoami:80"

Run dockroute next to it:

services:
  dockroute:
    image: ghcr.io/dockroute/dockroute:latest
    environment:
      DOCKROUTE_PROVIDER: cloudflare
      DOCKROUTE_OWNER_ID: home-lab
      CLOUDFLARE_API_TOKEN: ${CLOUDFLARE_API_TOKEN}
      # only needed for tunnel publishing:
      CLOUDFLARE_ACCOUNT_ID: ${CLOUDFLARE_ACCOUNT_ID}
      CLOUDFLARE_TUNNEL_ID: ${CLOUDFLARE_TUNNEL_ID}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    # No user/group setup needed: the entrypoint detects the socket's group,
    # grants it to the app user and drops privileges before starting.

Or start with the zero-credential dry run:

bun install
DOCKROUTE_DEFAULT_TARGET=192.168.1.10 bun start   # provider=log by default

Labels

Configuration

Health check

The image ships a Docker HEALTHCHECK (bun run src/healthcheck.ts): every successful reconcile touches a heartbeat file, and the check fails if it goes stale for longer than 3 × DOCKROUTE_RESYNC_SECONDS (minimum 90s). That means docker ps / docker inspect — and orchestrators that watch container health — report unhealthy when the Docker socket goes unreachable or the provider keeps failing to sync, not just when the process itself crashes.

No extra configuration is needed; running behind docker compose or CasaOS/Arcane/Portainer picks it up automatically from the image. Bring your own healthcheck: block only if you want different thresholds:

services:
  dockroute:
    image: ghcr.io/dockroute/dockroute:latest
    healthcheck:
      interval: 30s
      timeout: 10s
      start_period: 30s
      retries: 3

Safety model

• Every record dockroute creates gets a companion TXT record (_dockroute-a.whoami.example.com) carrying its owner id.
• Records without that proof of ownership are never modified, deleted or adopted — conflicts are logged and skipped.
• Orphan cleanup (container gone → records removed) only happens under the default sync policy and only for records this instance owns.
• Deletions wait out DOCKROUTE_DELETE_GRACE_SECONDS (default 60) of continuous absence, so a container restart does not take the hostname down. Creates and updates stay immediate: they are cheap and self-correcting, while a deleted record leaves a failure cached far beyond the outage. Raise it if your stacks pull images before starting.
• Tunnel ingress rules that dockroute did not create are preserved verbatim; dockroute assumes it is the only automated writer for the tunnels it manages.

Troubleshooting

DockRoute skips a misconfigured or conflicting entry instead of stopping the whole reconcile. Match the warning in docker logs dockroute to the table below, fix that entry, and the next reconcile will try it again.

Ownership conflicts are a safety feature, not an adoption failure. In particular, a data record with no DockRoute ownership TXT, or a record/TXT owned by a different DOCKROUTE_OWNER_ID, is skipped by design. A dangling ownership TXT from another owner is treated the same way. Resolve the existing record or ownership deliberately; do not bypass the ownership checks.

Docker socket preflight errors already include their remedy in the error text. If the socket is missing, is not a Unix socket, or cannot be read, follow the mount, DOCKER_SOCK, or group-access instruction printed with that error.

Development

bun install
bun test            # unit tests (in-memory fakes, no real HTTP)
bun run typecheck   # strict TypeScript
bun run lint        # Biome — bun run lint:fix to auto-fix

See CONTRIBUTING.md for the ground rules (ownership safety, anti-corruption layer, testing style) and how to add a provider.

License

MIT