How‐DockFlare‐Works.md

How DockFlare Works

DockFlare acts as an intelligent bridge between your Docker environment and your Cloudflare configuration. It automates the process of exposing Docker services securely to the internet via Cloudflare Tunnels and managing their Zero Trust Access policies.

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 (Tunnel ingress, DNS, and Access Applications) with currently running, labeled containers and any persisted state, respecting UI overrides for Access Policies.

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".
   • It also checks for Access Policy labels (e.g., cloudflare.tunnel.access.policy, cloudflare.tunnel.access.custom_rules, etc.) to define the initial desired access control for the service.

4. Rule & Access Policy Management:

   • Container Start: If a container starts with the required enable, hostname, and service labels:
     • DockFlare constructs an ingress rule (hostname + service target).
     • It determines the correct Cloudflare Zone ID (using zonename label or default CF_ZONE_ID).
     • It uses the Cloudflare API to add/verify a CNAME DNS record pointing the specified hostname to the tunnel's address (<tunnel-id>.cfargotunnel.com).
     • It updates the Cloudflare Tunnel's configuration file to include the new ingress rule.
     • Access Policy (Label-Driven Initial Setup): If Access Policy labels are present and the rule is not currently UI-overridden for its Access Policy, DockFlare creates or updates the corresponding Cloudflare Access Application.
     • It saves the managed rule details (including ingress, DNS info, Access Application ID, and UI override status) to its state file.
   • Container Stop/Die: If a labeled container stops:
     • DockFlare marks the corresponding ingress rule(s) and any associated, DockFlare-managed Access Application(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, the ingress rule from the tunnel configuration, and the Access Application (if managed by DockFlare and not overridden by a broader policy) via the Cloudflare API, then updates its state file.

5. Web UI Interaction (for Access Policies):

   • The Web UI allows for dynamic management of Access Policies for already established ingress rules.
   • UI Override: When an Access Policy is set or changed via the Web UI, this configuration takes precedence over any Access Policy labels defined on the container. This UI-set policy is persisted and will be reapplied even if DockFlare or the container restarts.
   • Revert to Labels: Users can explicitly choose to "Revert to Labels" via the UI, at which point DockFlare will remove the UI-managed Access Application (if any) and re-apply the Access Policy based on the container's current labels during the next reconciliation.

6. Periodic Reconciliation & Cleanup:

   • DockFlare periodically reconciles the state of managed rules, Cloudflare DNS, Tunnel ingress, and Access Applications with the actual running containers and their labels (always respecting UI overrides for Access Policies).
   • It also checks for rules whose grace period has expired and processes their deletion.

Example Workflow

1. Start DockFlare: You run the DockFlare container. 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"
   • cloudflare.tunnel.access.policy="authenticate" (Optional: defines initial Access Policy)
3. Automatic Configuration: DockFlare detects the new container. It automatically:
   • Creates a CNAME record my-app.example.com.
   • Adds an ingress rule to the tunnel for my-app.example.com.
   • If access.policy was "authenticate", it creates a Cloudflare Access Application requiring authentication for my-app.example.com.
   • Your service becomes accessible, potentially protected by the label-defined Access Policy.
4. UI Policy Adjustment (Optional): You navigate to the DockFlare Web UI. For my-app.example.com, you decide to change the Access Policy to "Bypass" using the "Edit Policy" dropdown.
   • DockFlare updates the Cloudflare Access Application to "Bypass".
   • The state for my-app.example.com is now marked as "UI Override" for its Access Policy. This "Bypass" policy will persist even if the nginx container restarts with the "authenticate" label.
5. Revert Policy (Optional): Later, you decide the "authenticate" label should take effect again. In the UI, you click "Revert to Labels" for my-app.example.com.
   • DockFlare deletes the UI-managed "Bypass" Access Application.
   • On the next reconciliation, it re-processes the container's labels and re-creates the "authenticate" Access Policy.
6. Graceful Deletion: You stop the nginx container.
   • DockFlare detects the stop event and marks the rule and its associated Access Application (whether label-derived or UI-overridden) for deletion after the grace period.
   • After the grace period, DockFlare removes the DNS record, ingress rule, and Access Application.

This dynamic process, combining declarative label-based setup with flexible UI overrides for access control, minimizes manual Cloudflare configuration while providing robust management.