How‐DockFlare‐Works.md

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): This is a critical step. 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. Label-Based Rule Management

When a container starts, DockFlare inspects its labels to decide what to do.

1. Prefix Detection: It looks for labels matching the configured LABEL_PREFIX (default: dockflare.).
2. Enablement: It checks for the essential dockflare.enable="true" label.
3. Rule Definition: It reads labels like dockflare.hostname, dockflare.path, and dockflare.service to construct one or more ingress rules for the container.
4. Cloudflare Configuration: For each valid rule, DockFlare automatically:
   • Creates or verifies a CNAME DNS record for the hostname.
   • Adds the ingress rule (hostname + path + service) to the Cloudflare Tunnel configuration.
   • If Access Policy labels (e.g., dockflare.access.policy) are present, it creates or updates the corresponding Cloudflare Access Application.
   • Saves the complete rule definition to state.json.

4. UI-Based Rule Management

DockFlare isn't limited to Docker containers. The Web UI provides powerful manual management capabilities.

• Manual Rules: You can add, edit, and delete ingress rules for non-Dockerized services (like a router or a VM). DockFlare manages the associated DNS records and ingress rules just as it does for container-based rules.
• Access Policy Overrides: For any rule (Docker or manual), you can use the UI to set or change its Access Policy. This UI-set policy is saved in state.json and takes precedence over any labels on a container, surviving restarts.
• Revert to Labels: The UI provides a "Revert" button to remove the policy override, allowing the container's labels to take control again during the next reconciliation.

5. Graceful Deletion & Cleanup

1. Container Stop: When a labeled container stops, DockFlare marks its rules for deletion but does not act immediately.
2. Grace Period: It waits for the duration specified in GRACE_PERIOD_SECONDS. This prevents rules from being torn down during a simple container restart or temporary stop. See Understanding Graceful Deletion.
3. Cleanup: After the grace period expires, a periodic cleanup task removes the CNAME DNS record, the ingress rule from the tunnel, and any associated Access Application from Cloudflare.

Example Workflow

1. Start DockFlare: You run the DockFlare container. It initializes, creates/connects to its tunnel, and starts the reconciled cloudflared agent.
2. Label a Container: You start a new nginx container with these labels:
   • dockflare.enable="true"
   • dockflare.hostname="my-app.example.com"
   • dockflare.service="http://nginx-container-name:80"
   • dockflare.access.policy="authenticate" (Optional initial policy)
3. Automatic Configuration: DockFlare detects the new container and automatically creates the DNS record, ingress rule, and "authenticate" Access Application. Your service is now live.
4. Add a Manual Rule: You use the Web UI to add a manual rule for nas.example.com pointing to http://192.168.1.50, with a "Bypass" Access Policy. DockFlare creates the necessary DNS and ingress rule.
5. Stop the Container: You stop the nginx container. DockFlare marks its rule for deletion after the grace period.
6. Restart the Container: Before the grace period ends, you start the nginx container again. DockFlare detects the start event and cancels the pending deletion, keeping your service online without interruption.

This dynamic process, combining declarative label-based setup with a flexible UI for manual rules and policy overrides, minimizes manual Cloudflare configuration while providing robust and resilient service exposure.