hapheus/cf-tunnel-sync repository overview

⁠🚀 Cloudflare Tunnel & Docker Sync

hapheus/cf-tunnel-sync automatically discovers Docker containers across your host and synchronizes Cloudflare Zero Trust Tunnel ingress rules and proxied DNS (CNAME) records in real time.

⁠✨ Features

• 🔄 Real-Time Docker Discovery: Automatically provisions ingress rules and DNS records when containers start or stop.
• 🎯 Fine-Grained Label Control: Configure custom hostnames, service protocols (http://, https://, tcp://), subpaths, and ports.
• 🔒 Zero Trust & Access Integration: Attach Cloudflare Access service tokens and custom origin request configurations.
• 🏢 Multi-Account & Multi-Tunnel: Route different compose stacks to distinct Cloudflare accounts and tunnels seamlessly.
• 🛡️ Blast-Radius Protection & Deletion Guard: Automatically prevents bulk route teardown on engine restart with configurable limits (MAX_DELETIONS_PER_SYNC=3).
• 🔍 Non-Mutating Preflight Validation: Validate Docker, tokens, and tunnels without mutations via --preflight or PREFLIGHT_ONLY=true.
• 🔮 Predictive Dry-Run & ChangePlan API: Audit exact route mutations via --dry-run and GET /api/change-plan.
• 🔬 6-Stage Truthful Diagnostics: Granular health checks ensuring zero false-positive sync reporting.
• 📊 Status Dashboard & Web UI: Built-in dashboard with real-time stage status indicators.

⁠🚀 Quick Start with Docker Compose

Deploy the core gateway stack alongside cloudflared:

services:
  cloudflared:
    image: cloudflare/cloudflared:latest
    container_name: cloudflared
    restart: unless-stopped
    command: tunnel run
    environment:
      - TUNNEL_TOKEN=${CLOUDFLARE_TUNNEL_TOKEN}
    networks:
      - tunnel_net

  cf-tunnel-sync:
    image: hapheus/cf-tunnel-sync:latest
    container_name: cf-tunnel-sync
    restart: unless-stopped
    environment:
      - CLOUDFLARE_API_TOKEN=${CLOUDFLARE_API_TOKEN}
      - CLOUDFLARE_ACCOUNT_ID=${CLOUDFLARE_ACCOUNT_ID:-}
      - CLOUDFLARE_TUNNEL_NAME=${CLOUDFLARE_TUNNEL_NAME}
      - DOMAIN_NAME=${DOMAIN_NAME}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - tunnel_net

networks:
  tunnel_net:
    name: tunnel_net

⁠🏷️ Container Labels Reference

Enable any container for automatic synchronization by applying Docker labels:

⁠⚙️ Core Configuration Reference

⁠🖥️ Optional Web Dashboard Companion

cf-tunnel-sync performs all synchronization, self-healing, and preflight checks autonomously without needing a GUI.

If you would like a visual status dashboard, add the companion hapheus/cf-tunnel-dashboard⁠ container to your stack:

  cf-tunnel-dashboard:
    image: hapheus/cf-tunnel-dashboard:latest
    container_name: cf-tunnel-dashboard
    restart: unless-stopped
    ports:
      - "8090:80"
    environment:
      - DASHBOARD_AUTH_ENABLED=false # Set to true to require basic auth
    networks:
      - tunnel_net

Alternatively, you can publish port 8090:8090 directly on cf-tunnel-sync to access its internal status API and Prometheus metrics.

⁠🔗 Links & Resources

• Dashboard Image: hapheus/cf-tunnel-dashboard⁠
• 10-Minute Quickstart Guide: github.com/hapheus/cf-docker-tunnel-sync/blob/main/QUICKSTART.md⁠
• Security & Socket Proxy Guide: github.com/hapheus/cf-docker-tunnel-sync/blob/main/docs/security.md⁠
• Operations & Teardown Runbook: github.com/hapheus/cf-docker-tunnel-sync/blob/main/docs/operations.md⁠
• Source Code & Documentation: github.com/hapheus/cf-docker-tunnel-sync⁠
• Issue Tracker: github.com/hapheus/cf-docker-tunnel-sync/issues⁠