Stop Manual Tunnel Config! Use DockFlare Instead

What if every container you deployed could instantly become publicly accessible through a secure, zero-trust tunnel—without ever touching the Cloudflare dashboard again?

If you've ever spent twenty minutes clicking through DNS records, tunnel ingress rules, and Access application configurations just to expose a single service, you know the pain. The repetitive slog. The configuration drift when you forget to update something. The midnight panic when you realize your manual tunnel setup broke after a container restart.

Here's the dirty secret most developers won't admit: we're still managing infrastructure like it's 2015. We write Docker Compose files with elegant service definitions, then immediately abandon that declarative paradise to click around a web dashboard like cavemen.

That ends now. DockFlare—the open-source tool that's making manual Cloudflare Tunnel configuration obsolete—turns your Docker labels into live, secured public endpoints automatically. No dashboard. No drift. No drama.

Ready to reclaim your time?

What Is DockFlare?

DockFlare is a self-hosted ingress and access-control plane purpose-built for Cloudflare Tunnel environments. Created by ChrispyBacon-dev and actively maintained with a growing community, it transforms how developers expose containerized services to the internet.

At its core, DockFlare operates as a reconciliation engine. It continuously collects your desired state—from Docker container labels, manually defined rules in its web UI, and optional remote agents—then computes the precise differences between what you want and what Cloudflare currently has. It applies only the necessary changes, keeping your tunnel configuration, DNS records, and Access policies in perfect sync.

The project is Swiss-made, GPL-3.0 licensed, and built with Python. It's currently at v3.1.2 with thousands of Docker pulls and a growing star count on GitHub. But what makes it genuinely exciting isn't just the feature list—it's the philosophy of infrastructure as intent.

Instead of imperative dashboard clicks, you declare what you want. DockFlare makes it so. This pattern—borrowed from Kubernetes controllers and GitOps workflows—finally arrives for the solo developer and small team who need Cloudflare Tunnel automation without enterprise complexity.

The tool also packs surprising depth beyond basic tunnel automation: a sovereign email suite, multi-domain email support, PWA-ready webmail, automated Cloudflare Workers provisioning, and multi-host distributed operation through lightweight agents. It's not merely a tunnel helper; it's becoming a comprehensive control plane for Cloudflare-native infrastructure.

Key Features That Eliminate Operational Toil

Automatic Service Discovery via Docker Labels

DockFlare watches Docker events in real-time. Spin up a container with dockflare.enable=true and a hostname label—your service is public within seconds. Tear it down—the tunnel ingress rule vanishes just as cleanly. This event-driven architecture eliminates stale configuration better than any cron-based cleanup script.

Reconciliation Engine with Drift Detection

The heart of DockFlare is its idempotent reconciliation loop. It persists desired state locally in encrypted files, compares against actual Cloudflare state via API, and applies surgical updates. Manual changes in the Cloudflare dashboard get detected and optionally preserved or overwritten based on your policy. No more wondering "did I update the tunnel?"

Sovereign Email Suite

This is where DockFlare surprises everyone. Beyond tunnels, it orchestrates a complete self-hosted email system using Cloudflare Email Routing as a stateless delivery layer. You get local data sovereignty with SQLite storage, R2 bucket integration for attachments, and automated DKIM key management. The PWA-ready Vue 3 webmail client supports offline access and push notifications across 13 languages.

Cloudflare Access Integration

Zero-trust isn't an afterthought. DockFlare natively manages Access Groups as reusable policy bundles, assigns them to services, and handles the full Access Application lifecycle. You can enforce authentication per-service without writing a single Cloudflare Access rule by hand.

Multi-Host Distributed Operation

Run a central master with lightweight agents on remote Docker hosts. Agents stream container events securely via Cloudflare Zero Trust service tokens—no VPN required. The master owns all policy decisions while agents execute locally. Scale from one Raspberry Pi to a dozen VPS instances seamlessly.

Backup, Restore, and Operational Safety

Encrypted configuration backups, runtime state preservation, and granular restore capabilities mean you can rebuild your entire control plane in minutes. The reference setup runs containers as non-root (UID/GID 65532) and uses a Docker socket proxy for least-privilege API access.

Real-World Use Cases Where DockFlare Dominates

1. The Homelab Developer with 40+ Services

You've got Plex, Nextcloud, Home Assistant, Pi-hole, a dozen self-hosted apps, and experimental projects spinning up weekly. Managing Cloudflare Tunnels manually? A part-time job. With DockFlare, your docker-compose.yml becomes your infrastructure definition. Add labels, deploy, done. New service on Friday night? It's live before your coffee cools.

2. The Agency Shipping Client Previews

Need ephemeral preview environments for every pull request? DockFlare labels in your CI/CD pipeline create on-demand public URLs with Access policies restricting them to your team. Merge the PR, container dies, tunnel rule auto-deletes. Zero manual cleanup, zero security sprawl.

3. The Distributed Startup with Edge Deployments

Your application runs across three regions with Docker hosts in each. Traditional tunnel management requires logging into each server's cloudflared instance. With DockFlare's agent mode, your central master sees all containers everywhere. One dashboard, unified policy, consistent zero-trust enforcement across every host.

4. The Privacy-Focused Operator Needing Sovereign Email

You want email without Google Workspace or Microsoft 365. DockFlare's email suite provisions Cloudflare Email Routing Workers, manages R2 storage for attachments, and gives you a modern webmail client—all while keeping message data under your control. Multi-domain support means you@personal.com and team@company.io coexist effortlessly.

5. The Platform Team Reducing Ticket Queue

Internal developers request public endpoints constantly. Instead of ticketing a platform engineer for Cloudflare dashboard access, publish the allowed label patterns and let teams self-serve. DockFlare's reconciliation ensures nothing violates your organizational policies while eliminating the bottleneck.

Step-by-Step Installation & Setup Guide

Prerequisites

Before starting, ensure you have:

• Docker and Docker Compose installed
• A Cloudflare account with your domain's DNS managed there
• Your Cloudflare Account ID and Zone ID for your primary domain
• A Cloudflare API token with these exact permissions:
  • Account:Cloudflare Tunnel:Write
  • Account:Account Settings:Read
  • Account:Access: Apps and Policies:Write
  • Account:Access: Organizations, Identity Providers, and Groups:Write
  • Account:Access: Service Tokens:Write
  • Zone:Zone:Read
  • Zone:DNS:Write

For email features, additionally grant:

• Workers Scripts:Write
• Workers KV Storage:Write
• Workers R2 Storage:Write
• Email Routing Addresses:Write
• Email Routing Rules:Write

Option A: One-Liner Install (Recommended)

The fastest path to running DockFlare:

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

This interactive script handles:

1. Installation directory selection (default: ~/dockflare/)
2. Local UI port configuration (default: 5000)
3. Optional Cloudflare Tunnel for DockFlare itself
4. Optional email suite enablement

Option B: Manual Docker Compose Setup

For full control, create the shared network first:

# Create the external network that DockFlare and your services will share
docker network create cloudflare-net

Then create your docker-compose.yml:

services:
  # Security-critical: proxy Docker socket with minimal permissions
  docker-socket-proxy:
    image: tecnativa/docker-socket-proxy:v0.4.1
    container_name: docker-socket-proxy
    restart: unless-stopped
    logging:
      driver: "none"  # Reduce noise; proxy is infrastructure
    environment:
      - DOCKER_HOST=unix:///var/run/docker.sock
      - CONTAINERS=1    # Required: list/watch containers
      - EVENTS=1        # Required: receive container lifecycle events
      - NETWORKS=1      # Required: inspect network connections
      - IMAGES=1        # Optional: image metadata
      - POST=1          # Required: for certain Docker operations
      - PING=1          # Healthcheck support
      - INFO=1          # System info for validation
      - EXEC=1          # Container exec operations
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - dockflare-internal

  # Initialize data directory with correct non-root permissions
  dockflare-init:
    image: alpine:3.20
    command: ["sh", "-c", "chown -R ${DOCKFLARE_UID:-65532}:${DOCKFLARE_GID:-65532} /app/data"]
    volumes:
      - dockflare_data:/app/data
    networks:
      - dockflare-internal
    restart: "no"  # One-shot initialization container

  # Main DockFlare control plane
  dockflare:
    image: alplat/dockflare:stable
    container_name: dockflare
    restart: unless-stopped
    ports:
      # Expose UI locally; comment out once tunneled with Access policy
      - "5000:5000"
    volumes:
      - dockflare_data:/app/data
    environment:
      - REDIS_URL=redis://redis:6379/0
      - REDIS_DB_INDEX=0
      - DOCKER_HOST=tcp://docker-socket-proxy:2375  # Never expose raw socket
    depends_on:
      docker-socket-proxy:
        condition: service_started
      dockflare-init:
        condition: service_completed_successfully
      redis:
        condition: service_started
    networks:
      - cloudflare-net      # Shared with your application containers
      - dockflare-internal  # Internal infrastructure only

  # Redis for coordination, caching, and pub/sub
  redis:
    image: redis:7-alpine
    container_name: dockflare-redis
    restart: unless-stopped
    # Disable persistence for cache-only usage; enable if needed
    command: ["redis-server", "--save", "", "--appendonly", "no"]
    logging:
      driver: "none"
    volumes:
      - dockflare_redis:/data
    networks:
      - dockflare-internal

  # Optional: Email backend (requires --profile email)
  dockflare-mail-manager:
    image: alplat/dockflare-mail-manager:stable
    container_name: dockflare-mail-manager
    restart: unless-stopped
    profiles: ["email"]  # Only starts with docker compose --profile email
    environment:
      - DOCKFLARE_MASTER_URL=http://dockflare:5000
      - MAIL_DATA_PATH=/data
    volumes:
      - mail_data:/data
    depends_on:
      dockflare:
        condition: service_started
    networks:
      - cloudflare-net
      - dockflare-internal

  # Optional: PWA webmail client (requires --profile email)
  dockflare-webmail:
    image: alplat/dockflare-webmail:stable
    container_name: dockflare-webmail
    restart: unless-stopped
    profiles: ["email"]
    environment:
      - DOCKFLARE_MASTER_URL=https://dockflare.TLD  # Replace with your domain
    labels:
      # Self-hosting DockFlare's own webmail through itself!
      - dockflare.enable=true
      - dockflare.hostname=mail.dockflare.TLD  # Replace with your domain
      - dockflare.service=http://dockflare-webmail:80
    depends_on:
      dockflare-mail-manager:
        condition: service_started
    networks:
      - cloudflare-net
      - dockflare-internal

volumes:
  dockflare_data:
  dockflare_redis:
  mail_data:

networks:
  cloudflare-net:
    name: cloudflare-net
    external: true  # Created manually; shared with application containers
  dockflare-internal:
    name: dockflare-internal

Launch the core services:

docker compose up -d

For the email suite:

docker compose --profile email up -d

Finally, open http://your-server-ip:5000 and complete the setup wizard with your Cloudflare credentials.

REAL Code Examples from the Repository

Example 1: Basic Service Exposure with Access Group

This is the canonical DockFlare experience—declare intent through labels, let automation handle the rest:

services:
  picoshare:
    image: mtlynch/picoshare
    labels:
      - "dockflare.enable=true"                    # Activate DockFlare management
      - "dockflare.hostname=files.example.com"     # Public hostname to create
      - "dockflare.service=http://picoshare:8080"  # Internal service target
      - "dockflare.access.group=nas-family"        # Reusable Access Group for auth

What's happening under the hood? DockFlare detects this container's creation, reads these labels, and executes a reconciliation sequence: create or update a Cloudflare Tunnel ingress rule mapping files.example.com → http://picoshare:8080, ensure the nas-family Access Group is attached as a policy, create the DNS CNAME record pointing to your tunnel, and verify the configuration is live. When you docker compose down, every rule is cleanly removed.

Example 2: Authentication-Required Internal Tool

For services needing individual authentication without a reusable group:

services:
  internal-tool:
    image: nginx:latest
    labels:
      - "dockflare.enable=true"
      - "dockflare.hostname=tool.example.com"
      - "dockflare.service=http://internal-tool:80"
      - "dockflare.access.policy=authenticate"           # Force authentication
      - "dockflare.access.email=admin@example.com,@example.com"  # Allow specific emails and entire domain

The power here is granularity. The @example.com syntax grants access to anyone with that domain, while admin@example.com explicitly includes that address. DockFlare translates this into Cloudflare Access policies with identity provider integration—no manual policy construction required. The authenticate policy means unauthenticated requests hit Cloudflare's login page before ever reaching your nginx container.

Example 3: Self-Hosting DockFlare with Access Protection

This meta-configuration shows DockFlare managing its own exposure—a pattern you'll use for any admin interface:

  dockflare:
    image: alplat/dockflare:stable
    # ... other configuration ...
    labels:
      # Main DockFlare interface with access policy
      - dockflare.enable=true
      - dockflare.hostname=dockflare.TLD              # Your domain
      - dockflare.service=http://dockflare:5000
      - dockflare.access.group=YOUR-ACCESS-GROUP-ID   # Restrict to authorized users
      
      # OAuth callback bypass—CRITICAL for OAuth loops
      - dockflare.0.hostname=dockflare.example.tld
      - dockflare.0.path=/auth/google/callback        # Exact callback path
      - dockflare.0.service=http://dockflare:5000
      - dockflare.0.access.group=public-default-bypass  # Allow unauthenticated callbacks

Why the bypass? When you authenticate with Google OAuth through Cloudflare Access, Google redirects back to your callback URL. If that callback path requires authentication, you create an infinite redirect loop: need auth to reach callback, but callback is part of auth. The indexed label syntax (dockflare.0.*, dockflare.1.*) creates additional ingress rules with path specificity, overriding the main policy for exact paths. This pattern is essential for any OAuth-protected service.

Example 4: Health Verification and API Inspection

After deployment, verify everything is operational:

# Basic liveness check—returns 200 if DockFlare is running
curl http://localhost:5000/ping

# Comprehensive system overview including reconciliation state,
# tunnel status, and discovered services
curl http://localhost:5000/api/v2/overview

These endpoints power monitoring integrations and troubleshooting workflows. The /api/v2/overview response includes reconciliation timestamps, last error messages, and per-service status— invaluable for building health dashboards or alerting rules.

Advanced Usage & Best Practices

Embrace the Hybrid Mode

Don't force everything into labels. Use Docker Label Mode for dynamic, ephemeral services and Manual Rule Mode for static infrastructure—VMs, physical appliances, or external SaaS proxies. DockFlare merges both sources intelligently; leverage this flexibility rather than fighting it.

Secure Your Socket Proxy

The tecnativa/docker-socket-proxy is your security boundary. Never mount /var/run/docker.sock directly into DockFlare. The proxy's environment variables explicitly whitelist only required Docker API operations, limiting blast radius if the main container is compromised.

Zone-Level Defaults for Wildcard Protection

Configure zone-level Access policies to catch wildcard subdomains. This safety net prevents accidental public exposure when someone forgets an access label. It's defense in depth for your entire domain.

Agent Enrollment with Zero Trust

For multi-host deployments, skip VPN complexity entirely. The Cloudflare Zero Trust service token authentication between master and agents means you can deploy agents on untrusted networks—coffee shop WiFi, residential connections, edge locations—with cryptographic certainty of identity.

Backup Before Major Changes

The encrypted backup/restore system captures configuration, runtime state, and email data. Trigger a backup before version upgrades or significant label refactoring. Recovery from catastrophic failure should take minutes, not hours.

Comparison with Alternatives

The verdict? Manual dashboard work doesn't scale. Raw cloudflared CLI automation requires significant scripting investment. Traefik solves routing but not Cloudflare-native features like Access and Tunnel orchestration. DockFlare occupies the sweet spot: Cloudflare-native, automation-first, with surprising depth for advanced use cases.

FAQ

Is DockFlare free and open source?

Yes. DockFlare is released under GPL-3.0 and available at no cost. The maintainer accepts sponsorships through GitHub Sponsors to support continued development.

Can I use DockFlare without Docker?

Partially. The Manual Rule Mode supports static hosts, VMs, and external services through the web UI. However, the automatic service discovery requires Docker. For non-Docker environments, agents can monitor remote Docker hosts while you manage rules centrally.

How does DockFlare handle Cloudflare API rate limits?

The reconciliation engine computes deltas before making API calls, applying only necessary changes. This minimizes API usage compared to naive "delete all, recreate all" approaches. For large-scale deployments, the idempotent design ensures retries are safe.

Is my data secure with the email features?

Email data resides in your local SQLite database and Cloudflare R2 buckets under your account. Cloudflare Email Routing acts as a stateless delivery layer—messages aren't stored long-term by Cloudflare. You maintain data sovereignty, unlike traditional email providers.

What happens if DockFlare goes down?

Existing tunnels continue operating—cloudflared maintains connections independently. However, new container discovery and configuration changes pause until DockFlare recovers. The encrypted state persistence means restoration is straightforward.

Can I migrate from manual tunnel setups?

Yes. The setup wizard includes import functionality for existing environment-based configurations. You can transition incrementally without service interruption.

How do I troubleshoot when labels don't work?

First, verify your Cloudflare API token scopes match the required permissions exactly. Confirm your domain maps to the correct Zone ID. Check that containers connect to the cloudflare-net network. Finally, inspect DockFlare's reconciliation logs in the web UI for specific error messages.

Conclusion

Manual Cloudflare Tunnel configuration is a tax on your time that compounds with every service you deploy. DockFlare eliminates that tax entirely, replacing dashboard drudgery with elegant label-based automation that scales from homelab hobbyist to distributed production cluster.

The reconciliation engine ensures your infrastructure stays aligned with your intent. The Access integration brings zero-trust security without zero-trust complexity. And the sovereign email suite? That's the kind of unexpected depth that signals a project built with genuine conviction.

I've watched too many developers burn evenings on tunnel configuration that should take seconds. DockFlare is the tool I wish existed years ago—and it's mature enough to trust today.

Stop configuring. Start labeling. Deploy DockFlare now and reclaim your time for building, not button-clicking.

Star the repository, join the community, and follow dockflare.app for documentation and updates.