How‐DockFlare‐Works.md

How DockFlare Works

DockFlare acts as an intelligent bridge between your Docker environment and your Cloudflare Tunnel configuration. It automates the process of exposing Docker services securely to the internet via Cloudflare.

Core Mechanism

1. Initialization:

   • On startup, DockFlare reads its configuration (from environment variables).
   • It connects to the Docker API to listen for container events (start, stop, die).
   • It connects to the Cloudflare API using your provided token.
   • It either creates a new Cloudflare Tunnel (using TUNNEL_NAME) or verifies an existing one. If managing the tunnel internally, it retrieves the tunnel token.
   • If running in internal mode, it starts and manages a cloudflared agent container using the tunnel token.
   • It performs an initial reconciliation to align Cloudflare's configuration with currently running, labeled containers and any persisted state.

2. Event Monitoring:

   • DockFlare continuously listens for Docker container events.

3. Label Detection:

   • When a container starts or stops, DockFlare inspects its labels.
   • It looks for labels matching the configured LABEL_PREFIX (default: cloudflare.tunnel.).
   • Crucially, it checks for cloudflare.tunnel.enable="true".

4. Rule Management:

   • Container Start: If a container starts with the required enable, hostname, and service labels, DockFlare:
     • Constructs an ingress rule (hostname + service target).
     • Determines the correct Cloudflare Zone ID (using zonename label or default CF_ZONE_ID).
     • Uses the Cloudflare API to add a CNAME DNS record pointing the specified hostname to the tunnel's address (<tunnel-id>.cfargotunnel.com).
     • Updates the Cloudflare Tunnel's configuration file to include the new ingress rule mapping the hostname to the internal service.
     • Saves the managed rule details to its state file.
   • Container Stop/Die: If a labeled container stops:
     • DockFlare marks the corresponding ingress rule(s) for deletion.
     • It schedules the actual deletion based on the GRACE_PERIOD_SECONDS. See Understanding Graceful Deletion.
     • Once the grace period expires, DockFlare removes the CNAME record and the ingress rule from the tunnel configuration via the Cloudflare API and updates its state file.

5. Periodic Cleanup: DockFlare periodically checks for rules whose grace period has expired and processes their deletion.

Example Workflow

1. Start DockFlare: You run the DockFlare container (e.g., using docker compose up -d). It initializes, creates/connects to the tunnel, and starts the cloudflared agent (in internal mode).
2. Label Your Containers: You start a new web service container (e.g., nginx) and add labels:
   • cloudflare.tunnel.enable="true"
   • cloudflare.tunnel.hostname="my-app.example.com"
   • cloudflare.tunnel.service="http://nginx-container-name:80"
3. Automatic Configuration: DockFlare detects the new container and its labels. It automatically:
   • Creates a CNAME record my-app.example.com pointing to your tunnel.
   • Adds an ingress rule to the tunnel: hostname: my-app.example.com, service: http://nginx-container-name:80.
   • Your service my-app.example.com becomes accessible via the Cloudflare Tunnel.
4. Graceful Deletion: You stop the nginx container (docker stop nginx-container-name).
   • DockFlare detects the stop event.
   • It marks the my-app.example.com rule for deletion after the configured grace period (e.g., 8 hours).
   • If the container remains stopped after 8 hours, DockFlare removes the DNS record and the ingress rule. If you restart the container within the grace period, the deletion is typically cancelled.

This dynamic process eliminates the need for manual Cloudflare dashboard configuration for every service you wish to expose.