DockFlare: Docker Labels as the Control Plane for Cloudflare Tunnels

The drift problem DockFlare was written to remove

Self-hosted stacks change faster than Cloudflare dashboards do. You add a service, point a hostname at it, create a DNS record, add an ingress rule to the tunnel, and then decide the service needs an Access policy. Each of those steps lives in a different part of the Cloudflare UI, and none of them lives next to the container definition. When you rename or move a container, the tunnel configuration quietly stops matching reality.

DockFlare's answer is to treat Docker labels as the desired state and Cloudflare as the thing to be reconciled. The README describes it as a "self-hosted ingress and access-control plane for Cloudflare Tunnel environments" that "continuously translates your desired state into Cloudflare configuration." The audience is narrow and specific: people running containers at home or in a small lab, who already have a Cloudflare account and a domain on it, and who would rather write a label than click through a dashboard. If you do not have a Cloudflare account with a zone you control, none of this applies to you.

How the reconciliation loop actually works

The README lays out a four-step cycle. DockFlare collects desired state from three sources: Docker labels, manual rules entered in the web UI, and containers reported by remote agents. It then computes deltas against two other states: the state it persisted locally, and the state it reads back from the Cloudflare API. Only then does it apply updates for ingress, DNS and Access resources, and finally update local runtime state so that cloudflared stays aligned with what was just written.

The important detail is that Cloudflare is treated as the source of truth for tunnels, DNS, email and Access resources, while DockFlare keeps its own encrypted copy of configuration and runtime state. That two-sided comparison is what makes the tool more than a one-shot setup script: a record deleted by hand in the dashboard is a delta on the next pass, not something DockFlare silently ignores. The architecture table names the moving parts: a Master component holding the UI, encrypted config and orchestration logic; a Mail Manager for the optional email profile; a Vue 3 webmail client; Redis for cache, coordination and pub/sub signalling; an Agent for remote hosts; and cloudflared itself as the connector runtime.

That is a lot of components for a routing tool, and the email suite in particular is a separate product living inside the same repository. If you only want label-driven tunnels, you are carrying code you will not use.

Installing DockFlare and exposing your first container

The README gives a one-liner installer that walks through the install directory, the local UI port, and whether to configure a tunnel for DockFlare itself. The default install directory is `~/dockflare/` and the default UI port is `5000`.

bash <(curl -fsSL https://dockflare.app/install.sh)

The script prompts for each choice in turn; the README notes that enabling the email profile adds dockflare-mail-manager and dockflare-webmail to the stack. Prerequisites listed are Docker and Docker Compose, a Redis instance (the quick-start stack includes one), a Cloudflare account, an Account ID, a Zone ID for your primary domain, and an API token carrying the permissions enumerated in the README, among them `Account:Cloudflare Tunnel:Write`, `Zone:Zone:Read` and `Zone:DNS:Write`.

The repository's docker-compose.yml shows what the stack looks like. A docker-socket-proxy container sits in front of the Docker socket, and dockflare runs from `alplat/dockflare:stable` with port 5000 published.

services:
  dockflare:
    image: alplat/dockflare:stable
    container_name: dockflare
    restart: unless-stopped
    ports:
      - "5000:5000"
    labels:
      - dockflare.enable=true
      - dockflare.hostname=dockflare.TLD
      - dockflare.service=http://dockflare:5000

Those three labels are the whole contract for a service: enable it, give it a hostname, point it at an internal address. The compose file also shows a commented `dockflare.access.group` key for attaching a custom access policy, and a numbered variant (`dockflare.0.hostname`, `dockflare.0.path`, `dockflare.0.service`, `dockflare.0.access.group`) used to carve out an OAuth callback path such as `/auth/google/callback` that bypasses the policy on the main interface. After the stack is up, the UI answers on port 5000 and the README suggests commenting that port out once the interface is reachable through a tunnel with an Access policy in front of it.

Where DockFlare stops being the right tool

The design assumes Cloudflare is in the path. Traffic reaches your containers through Cloudflare's edge, and Access policies are Cloudflare Access applications, not something DockFlare implements itself. If your requirement is that no third party sits between the user and the service, or if you need TLS terminated on your own hardware with certificates you control, this is the wrong layer. A reverse proxy that terminates locally is a different product with a different trust boundary.

The API token is the other hard edge. The README lists a token with write access to tunnels, DNS and Access, plus optional Workers, KV, R2 and Email Routing scopes for the email profile. That is a broad credential, and DockFlare's usefulness depends on it being valid and correctly scoped. An under-scoped token does not degrade gracefully into a read-only mode; the reconciliation steps that need write access simply cannot complete. The README does not document rollback, so if a reconciliation pass writes an ingress rule you did not intend, there is no described undo path beyond correcting the label and waiting for the next pass. Treat the first run against a test hostname, not a production one.

Scale is another boundary. The multi-host story runs through a Master plus lightweight agents, with agent communication over Cloudflare Zero Trust service tokens. That is a reasonable fit for a handful of machines. It is not a Kubernetes ingress controller, and nothing in the README suggests it is trying to be.

DockFlare compared with running cloudflared yourself

The obvious alternative is cloudflared with a hand-written configuration file. You run the connector, list your ingress rules, and restart it when the file changes. The difference is where the state lives. With a config file, the file is the source of truth and Cloudflare is told what to do; a container that moves means editing the file and reloading. With DockFlare, the labels on the containers are the source of truth and DockFlare computes the difference against what Cloudflare currently holds, including changes made outside the tool.

That is a real trade. A config file is one artifact you can read, diff and version. DockFlare replaces it with a running process, an encrypted state store and a Redis dependency, and you gain automatic DNS and Access application management that a bare cloudflared config does not give you. If your service list is stable and small, the config file is less machinery for the same result. If hostnames churn and Access policies need to follow them, the reconciliation loop earns its keep.

A second comparison point is the manual ingress rules feature. DockFlare does not force everything through labels; the README lists manual rule management for non-Docker workloads, which means a machine outside your Docker host can still be routed without pretending it is a container.

Maintenance, releases and the licence question

The repository is not archived, and the last push was on 2026-09-20. Release cadence is visible in the tags: v3.1.3 on 2026-08-05, v3.1.5 on 2026-09-01, v3.1.6 on 2026-09-20. Patch releases arriving weeks apart suggests active work, and the changelog file at the repository root is where that work is recorded.

Upgrade cost is the part worth thinking about before you commit. The compose file pins `alplat/dockflare:stable`, so pulling the image moves you forward, but the stack also contains Redis, a socket proxy, and optionally the mail manager and webmail services. Each of those is another image to keep current. The README advertises backup and restore of encrypted configuration, runtime state and email data, which is the mechanism you would rely on before an upgrade, though it does not describe a downgrade path.

The licence situation deserves a plain statement rather than a guess. The repository's licence badge and the LICENSE.MD file point to GPL-3.0, while the metadata field returned for this repository is NOASSERTION, meaning the hosting platform did not classify it. If you plan to redistribute DockFlare or build a product around it, read LICENSE.MD directly and get your own advice; the badge is not a substitute for the file.

Editorial conclusion

Adopt DockFlare if you already run Docker Compose, hold a Cloudflare account, and are tired of editing tunnel ingress by hand every time a container moves. Skip it if you have no Cloudflare account, or if you want a proxy that terminates TLS on your own host rather than leaning on Cloudflare's edge. Before deploying, verify that your API token carries Account:Cloudflare Tunnel:Write, Zone:DNS:Write and the Access scopes, and confirm the reconciliation behaviour against a throwaway hostname rather than your production one.

Frequently asked questions

Official sources

1. ChrispyBacon-dev/DockFlare on GitHub
2. Issues
3. Project website
4. README
5. Releases