Skip to content

How‐DockFlare‐Works.md

Jump to bottom
Chris edited this page Jun 22, 2025 · 6 revisions

How DockFlare Works

DockFlare acts as an intelligent, self-hosted controller that bridges your Docker environment with your Cloudflare account. It automates the entire lifecycle of exposing services securely to the internet via Cloudflare Tunnels and managing their Zero Trust Access policies.

Core Mechanism

The process can be broken down into several key stages:

1. Startup & Reconciliation

On startup, DockFlare performs a comprehensive initialization and reconciliation sequence:

  1. Configuration Loading: Reads all settings from the .env file.
  2. State Loading: Loads the state.json file to understand previously managed rules and UI overrides.
  3. Cloudflare API Connection: Connects to the Cloudflare API using your provided token.
  4. Tunnel Initialization: Creates a new Cloudflare Tunnel (using TUNNEL_NAME) or verifies an existing one. In managed mode, it retrieves the necessary tunnel token.
  5. Agent Reconciliation (Managed Mode): DockFlare inspects the managed cloudflared-agent container (if it exists) and compares its configuration (network, image version) against the current .env settings. If a mismatch is found, it automatically recreates the agent to ensure it's always running with the correct configuration. If the agent doesn't exist, it's created.
  6. Initial Scan: DockFlare performs a full scan of all running Docker containers, processing their labels to establish a "desired state" of ingress rules.
  7. State Alignment: It compares this desired state with the loaded state.json and the actual configuration on Cloudflare, making any necessary API calls to align DNS records, tunnel ingress rules, and Access Applications.

2. Continuous Event Monitoring

Once initialized, DockFlare continuously listens for Docker container events (e.g., start, stop, die).

3. Rule & Policy Management

Based on Docker events or UI actions, DockFlare manages all aspects of a service's exposure:

  • From Docker Labels: When a container starts, DockFlare reads its dockflare.* labels to automatically create or update the corresponding DNS CNAME record, Tunnel Ingress Rule, and initial Cloudflare Access Policy.
  • From the Web UI: Users can create/edit/delete rules for non-Docker services and override the Access Policy for any rule. These UI-driven changes are saved to state.json and take precedence over container labels.

4. Graceful Deletion & Cleanup

When a container stops, its rules are marked for deletion after a configurable grace period. This prevents downtime during simple restarts. After the period expires, a background task removes all associated resources (DNS, Ingress Rule, Access Application) from Cloudflare.

Design Philosophy: Why the API-Centric Approach?

A common question is why DockFlare relies heavily on the Cloudflare API instead of just using the cloudflared command-line tool or a tunnel's specific credentials (cert.pem). The answer lies in the granularity of control required for automation.

API Token vs. cloudflared login

DockFlare uses two different types of credentials for two different jobs:

  1. The cloudflared Agent's Token: This is a tunnel-specific credential that the cloudflared agent container uses for one job only: establishing the secure connection to Cloudflare's edge. DockFlare retrieves this token and passes it to the agent.
  2. Your Cloudflare API Token: This is what gives DockFlare its "brains." A broader API token is necessary because the tunnel's own credentials cannot perform critical automation tasks, such as:
    • Managing Access Policies: Creating, updating, and deleting Zero Trust applications and rules.
    • Managing DNS Records: Juggling dozens of CNAME records across multiple domains for all the services pointing to the one tunnel.
    • Managing Tunnels Themselves: Finding, creating, or listing other tunnels on the account for the UI.

While providing an API token requires care, it's the only way to achieve the level of automation DockFlare offers. Best Practice: Always create a dedicated API Token for DockFlare with only the minimum required permissions (Zone:DNS:Edit and Account:Cloudflare Tunnel:Edit).

Direct API Calls vs. cloudflared CLI Commands

While the cloudflared command-line tool is excellent for running the tunnel, DockFlare uses direct API calls for all management tasks for several key reasons:

  • Granular Control: The API offers detailed control over Access Policies and complex DNS configurations that simply aren't available via the CLI.
  • Reliable State Management: Receiving structured JSON responses from an API is far more reliable for automation than parsing human-readable text output from a CLI command, which can change between versions and break the application.
  • Service-Level Cleanup: cloudflared tunnel delete is an all-or-nothing command that deletes the entire tunnel. DockFlare's API-based approach allows it to manage rules at a granular level. When one container out of ten stops, DockFlare surgically removes only the CNAME and ingress rule for that one service, leaving the other nine (and the tunnel itself) completely untouched.

In short, DockFlare uses the cloudflared binary for what it does best—running the secure connection—and the Cloudflare API for what it does best: providing the robust, structured control needed for powerful automation.

Clone this wiki locally