Automate Cloudflare Tunnels with Docker Labels

Go from container to publicly-secured URL in seconds. No manual Cloudflare dashboard configuration required.

🌐 Website · 📚 Documentation · 🐛 Report a Bug · ❤️ Sponsor

---

Introduction

DockFlare is a powerful, self-hosted ingress controller that simplifies Cloudflare Tunnel and Zero Trust management. It uses Docker labels for automated configuration while providing a robust web UI for manual service definitions and policy overrides.

It enables secure, hassle-free public access to both Dockerized and non-Dockerized applications with minimal direct interaction with Cloudflare, making it the perfect tool for centralizing and streamlining your access management.

✨ What's New in DockFlare 3.0: Multi-Server & Agent Release

DockFlare 3.0 elevates the project from a single-node helper to a distributed fleet orchestrator.

• DockFlare Agent: Deploy the lightweight agent next to workloads on any host. Agents stream container events, maintain their own tunnels, and obey commands from the master.
• Fleet Management UI: A dedicated Agents page lets you enrol nodes with API keys, assign tunnels, monitor health, and trigger actions without touching the CLI.
• Security Hardening: Master API calls now require an explicit master key that is revealed on demand, agent tokens are revocable, and sensitive setup routes stay locked after onboarding. The DockFlare Agent container now runs as the unprivileged dockflare user (UID/GID 65532) and the reference compose stack proxies Docker access through tecnativa/docker-socket-proxy for least-privilege isolation.
• Redis Backplane: The master now uses Redis for caching, queue fan-out, and cross-process signalling—ready for future scaling.
• Full Backup & Restore: Download a complete, timestamped archive of your DockFlare instance (including encrypted credentials and agent keys) and restore it via the UI to rebuild a master in minutes.
• Documentation Refresh: New guides cover the master/agent architecture, configuration tips, and upgrade considerations.

Getting Started & Documentation

For comprehensive documentation, please refer to the official project website:

• Quick Start Guide - Step-by-step guide to get up and running.
• Label Reference - Detailed information on all available Docker labels.
• Advanced Configuration - Details on multi-zone setups, external mode, and more.

Prerequisites

Before you begin, ensure you have the following:

• Docker & Docker Compose installed.
• A Redis instance (the quick-start stack below runs one for you).
• A Cloudflare Account.
• Your Cloudflare Account ID.
• The Zone ID for the domain you wish to use.
• A Cloudflare API Token with the following permissions:
  • Account:Cloudflare Tunnel:Edit
  • Account:Account Settings:Read
  • Account:Access: Apps and Policies:Edit
  • Zone:Zone:Read
  • Zone:DNS:Edit

🚀 Quick Start Docker Compose

1. Create docker-compose.yml:

   version: '3.8'
   services:
     docker-socket-proxy:
       image: tecnativa/docker-socket-proxy:v0.4.1
       container_name: docker-socket-proxy
       restart: unless-stopped
       environment:
         - DOCKER_HOST=unix:///var/run/docker.sock
         - CONTAINERS=1
         - EVENTS=1
         - NETWORKS=1
         - IMAGES=1
         - POST=1
         - PING=1
         - INFO=1
         - EXEC=1
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock
       networks:
         - dockflare-internal
   
     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"
   
     dockflare:
       image: alplat/dockflare:stable
       container_name: dockflare
       restart: unless-stopped
       ports:
         - "5000:5000"
       volumes:
         - dockflare_data:/app/data
       environment:
         - REDIS_URL=redis://redis:6379/0
         - REDIS_DB_INDEX=0  # Optional: specify Redis database index (0-15) for isolation from other containers
         - DOCKER_HOST=tcp://docker-socket-proxy:2375
       depends_on:
         docker-socket-proxy:
           condition: service_started
         dockflare-init:
           condition: service_completed_successfully
         redis:
           condition: service_started
       networks:
         - cloudflare-net
         - dockflare-internal
   
     redis:
       image: redis:7-alpine
       container_name: dockflare-redis
       restart: unless-stopped
       command: ["redis-server", "--save", "", "--appendonly", "no"]
       volumes:
         - dockflare_redis:/data
       networks:
         - dockflare-internal
   
   volumes:
     dockflare_data:
     dockflare_redis:
   
   networks:
     cloudflare-net:
       name: cloudflare-net
       external: true
     dockflare-internal:
       name: dockflare-internal

2. Run DockFlare:

   docker compose up -d

3. Complete the Pre-Flight Setup: Open http://your-server-ip:5000 in your browser. You will be guided through a one-time setup wizard to enter your Cloudflare credentials and create a password for the UI.

4. For Existing Users: If you are upgrading, DockFlare will detect your old .env file and automatically guide you through a quick migration process.

The master now runs as the unprivileged dockflare user (UID/GID 65532) and only talks to Docker through the bundled socket proxy. If you bind-mount a host directory instead of using the named volume above, make sure it is writable by that UID/GID or adjust the DOCKFLARE_UID/DOCKFLARE_GID build args.

💡 Need to manage workloads on additional hosts? Deploy the DockFlare Agent next to your containers, enrol it from the master UI, and let DockFlare orchestrate the tunnels for you. Both the master and agent images run as the non-root dockflare user by default, so align your volume permissions or override the build args if required. A full guide is available in the new Multi-Server Agent documentation.

🏷️ How It Works & Labeling Containers

DockFlare's power comes from its flexible, layered approach to configuration.

• Access Groups First (Recommended): The easiest and most maintainable way to secure services is to create an Access Group in the UI and apply it with a single label.
• Individual Labels for One-Offs: For services that don't fit a group, you can still use individual dockflare.access.* labels for initial configuration.
• UI for Dynamic Overrides: The Web UI can override the access policy for any service, whether it was configured by a group or by individual labels. UI changes are persistent and stored in the encrypted dockflare_config.dat file.
• DNS Zone Auto-Detection: Starting with v3.0, DockFlare automatically infers the correct Cloudflare zone from each hostname. You only need dockflare.zonename when intentionally sending a record to a different zone.

📝 Labeling Your Containers (Examples)

1. Recommended Method: Using an Access Group

Assuming you created an Access Group with the ID nas-family in the UI:

services:
  picoshare:
    image: mtlynch/picoshare
    labels:
      - "dockflare.enable=true"
      - "dockflare.hostname=files.example.com"
      - "dockflare.service=http://picoshare:8080"

      # Apply the entire policy with one label:
      - "dockflare.access.group=nas-family"

2. Alternative Method: Using Individual Labels

For a service with a unique, one-off policy:

services:
  my-service:
    image: nginx:latest
    labels:
      - "dockflare.enable=true"
      - "dockflare.hostname=my-service.example.com"
      - "dockflare.service=http://my-service:80"

      # Optional individual labels for a one-off policy
      - "dockflare.access.policy=authenticate"
      - "dockflare.access.allowed_idps=YOUR_IDP_UUID_HERE"

🛡️ All Access Policy Labels (for one-off configs)

Use these labels only when not using dockflare.access.group.

Label	Description	Default	Example
dockflare.access.policy	Type: bypass (public app), authenticate (IdP login), default_tld (inherits from *.domain.com policy). If unset, service is public (no Access App).	(None/Public)	dockflare.access.policy="authenticate"
dockflare.access.name	Custom name for the Cloudflare Access Application.	DockFlare-{hostname}	dockflare.access.name="My Web App Access"
dockflare.access.session_duration	Session duration (e.g., 24h, 30m).	24h	dockflare.access.session_duration="1h"
dockflare.access.custom_rules	JSON string array of Cloudflare Access Policy rules. Overrides basic access.policy decisions.	(None)	'...=[{"email":{"email":"[email protected]"},"action":"allow"},{"action":"block"}]'
...	Other access.* labels for launcher visibility, IdPs, etc. are also available.

Known Issues

• Running Cloudflare WARP locally (for example on macOS) can block the managed cloudflared container from establishing a tunnel, resulting in repeated handshake failures and missing cert.pem errors. Disable WARP before testing DockFlare on the same host.
• Deleting the DockFlare data volume clears stored agent API keys. Generate new keys and re-enroll agents after a reset; stale keys will be refused.

License

DockFlare is open-source software licensed under the GPL-3.0 license.

Star History