Sign inSign up
cf-tunnel-sync logo

hapheus/cf-tunnel-sync

By hapheus

•Updated 1 day ago

Automated route and DNS synchronization between Docker containers and Cloudflare Tunnels

Image
Networking
Developer tools
0

10K+

hapheus/cf-tunnel-sync repository overview

⁠Cloudflare Tunnel Docker Synchronizer (hapheus/cf-tunnel-sync)

Automate Cloudflare Tunnel ingress routing and DNS CNAME records directly from Docker container labels.

The synchronizer acts as the control plane (managing configuration via the Cloudflare API), while the official cloudflare/cloudflared⁠ container acts as the data plane (routing encrypted tunnel traffic to your Docker network).


⁠Quick Start with Docker Compose

Run cf-tunnel-sync alongside cloudflared. Both containers share a dedicated Docker bridge network and a lightweight token volume (cf_token_data).

services:
  cloudflared:
    image: cloudflare/cloudflared:2025.5.0
    restart: unless-stopped
    command: tunnel --no-autoupdate run --token-file /etc/cloudflared/token
    volumes:
      - cf_token_data:/etc/cloudflared
    networks:
      - cf-tunnel-net
    depends_on:
      cf-tunnel-sync:
        condition: service_healthy

  cf-tunnel-sync:
    image: hapheus/cf-tunnel-sync:latest
    restart: unless-stopped
    environment:
      CLOUDFLARE_API_TOKEN: ${CLOUDFLARE_API_TOKEN}
      CLOUDFLARE_TUNNEL_NAME: ${CLOUDFLARE_TUNNEL_NAME:-homelab-tunnel}
      DOMAIN_NAME: ${DOMAIN_NAME}
      CF_NETWORK_NAME: cf-tunnel-net
      DASHBOARD_ENABLED: "false"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - cf_token_data:/etc/cloudflared
    networks:
      - cf-tunnel-net
    healthcheck:
      test: ["CMD", "python", "healthcheck.py"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 5s

networks:
  cf-tunnel-net:
    name: cf-tunnel-net
    driver: bridge

volumes:
  cf_token_data:

⁠Exposing Applications

Attach your application container to cf-tunnel-net and specify the hostname and internal container port:

services:
  my-app:
    image: nginx:alpine
    restart: unless-stopped
    networks:
      - cf-tunnel-net
    labels:
      cf.tunnel.hostname: app.example.com
      cf.tunnel.port: "80"

networks:
  cf-tunnel-net:
    external: true

Note

Service discovery is driven directly by `cf.tunnel.hostname` and `cf.tunnel.port`; an explicit `cf.tunnel.enable` label is not required to opt in.

No host port forwarding (e.g. 80:80 or 443:443) is required. Traffic flows securely through Cloudflare's edge into the container.


⁠Configuration Reference

VariableRequiredDefaultDescription
CLOUDFLARE_API_TOKENYes—Scoped Cloudflare API token with Zone DNS and Account Tunnel edit permissions.
DOMAIN_NAMEYes—Your registered domain zone (e.g., example.com).
CLOUDFLARE_TUNNEL_NAMEYes—Dedicated tunnel name (created automatically if missing).
CLOUDFLARE_ACCOUNT_IDNoAuto-detectedCloudflare Account ID (inferred from domain zone when omitted).
CF_NETWORK_NAMENocf-tunnel-netDocker network name shared with the cloudflared connector.
SYNC_FALLBACK_INTERVALNo900Fallback reconciliation interval in seconds (Docker events trigger instant syncs).
MAX_DELETIONS_PER_SYNCNo3Safety limit: prevents accidental mass deletion during sync cycles.
ALLOW_MASS_DELETIONSNofalseExplicitly overrides MAX_DELETIONS_PER_SYNC when bulk deletion is intentional.
DRY_RUNNofalseWhen true, logs planned changes without mutating Cloudflare API resources.
PREFLIGHT_ONLYNofalseWhen true, runs preflight resource inspection and exits immediately.
LOG_FORMATNotextLogging output format: text or json (for structured logging).
NOTIFICATION_WEBHOOK_URLNo—Optional webhook URL for Discord/Slack/generic sync notifications and alerts.
DASHBOARD_ENABLEDNofalseEnables the embedded status UI on internal port 8090.

⁠Safety & Operational Notes

  • Preflight Inspection: Run non-mutating checks without changing live resources:
    docker compose exec cf-tunnel-sync python app.py --preflight
    
    (Alternatively set PREFLIGHT_ONLY=true).
  • Scoped API Tokens: Never use a Global API Key. Use a token scoped to Account: Cloudflare Tunnel: Edit and Zone: DNS: Edit. See Permissions Guide⁠.
  • Socket Security: The Docker socket mount (/var/run/docker.sock) grants root-equivalent host access. On untrusted environments, use the Docker Socket Proxy example⁠.
  • Access Labels: Labels like cf.tunnel.access display metadata in the UI only; they do not configure Cloudflare Access authorization policies.

Tag summary

Content type

Image

Digest

sha256:d4b0675ef…

Size

25.6 MB

Last updated

1 day ago

docker pull hapheus/cf-tunnel-sync