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 self-hosted ingress and access-control plane for Cloudflare Tunnel environments. It continuously translates your desired state into Cloudflare configuration by combining Docker labels, manual rules from the web UI, and optional remote agents.

It was built to remove repetitive dashboard work from fast-changing self-hosted environments. Instead of manually updating DNS records, tunnel ingress rules, and Access applications, you define intent once and DockFlare reconciles it.

The result is a set-it-and-forget-it workflow: less operational drift, more reliable service exposure, and one place to manage routing and access decisions.

Core Capabilities

• Automatic service discovery from Docker labels.
• Manual ingress rule management for non-Docker workloads.
• Cloudflare Tunnel ingress orchestration, including advanced origin options.
• Access Group and reusable policy management with application assignment.
• Cloudflare Access application lifecycle management.
• Multi-zone DNS handling and zone-aware record placement.
• Multi-host operation through a master and lightweight agents.
• Backup and restore of encrypted configuration and runtime state.
• Deep-link shortcuts into Cloudflare Zero Trust pages from the DockFlare UI.

Architecture Overview

Detailed architecture guide: https://dockflare.app/architecture

Component	Purpose
DockFlare Master	Web UI, encrypted config/state, reconciliation, Cloudflare API orchestration
Redis	Shared cache, coordination, and pub/sub signaling
DockFlare Agent	Remote host watcher and command executor for distributed deployments
cloudflared	Tunnel connector runtime managed per deployment mode
Cloudflare API	Source of truth for Tunnel, DNS, and Access resources

Reconciliation Flow

1. DockFlare collects desired state from labels, manual rules, and agent-reported containers.
2. It computes deltas against persisted state and Cloudflare state.
3. It applies updates for ingress, DNS, and Access resources.
4. It updates local runtime state and keeps cloudflared aligned.

Getting Started

For full setup documentation, use the project docs site:

• Quick Start Guide
• Container Label Reference
• Advanced DNS and Zone Management
• Multi-Server Agent Setup

Prerequisites

• Docker and Docker Compose.
• A Redis instance (the quick-start stack below includes one).
• A Cloudflare account.
• Cloudflare Account ID.
• Cloudflare Zone ID for your primary domain.
• Cloudflare API token with these permissions:
  • Account:Cloudflare Tunnel:Edit
  • Account:Access: Organizations, Identity Providers, and Groups:Edit
  • Account:Account Settings:Read
  • Account:Access: Apps and Policies:Edit
  • Zone:Zone:Read
  • Zone:DNS:Edit

Quick Start Docker Compose

Before first launch, create the shared network once:

docker network create cloudflare-net

1. Create docker-compose.yml:

version: '3.8'
services:
  docker-socket-proxy:
    image: tecnativa/docker-socket-proxy:v0.4.1
    logging:
      driver: "none"
    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
      - DOCKER_HOST=tcp://docker-socket-proxy:2375
      - LOG_LEVEL=ERROR
    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. Start DockFlare:

docker compose up -d

3. Open http://your-server-ip:5000 and complete the setup wizard.

If you are migrating from older environment-based setups, DockFlare can import existing values during onboarding.

Configuration Modes

Docker Label Mode

Use container labels to declare hostname, service target, and access behavior. DockFlare observes lifecycle events and reconciles records and ingress rules automatically.

Detailed label reference: https://dockflare.app/docs/container-labels

Manual Rule Mode

Create and edit routes directly in the UI for static hosts, VMs, appliances, or external services. Manual rules support HTTP/HTTPS advanced origin options and are persisted in DockFlare state.

Hybrid Mode

Use labels for most workloads while managing exceptions in UI. DockFlare merges both sources into one reconciliation model.

Agent Mode (Multi-Server)

Run a central master with agents on remote Docker hosts. Agents stream host-local container events and execute commands while the master owns policy and Cloudflare configuration decisions.

Multi-agent setup guide: https://dockflare.app/docs/multi-server-agent

Access Control Model

DockFlare uses Access Groups as the primary abstraction for reusable access intent.

• One Access Group can be attached to multiple services.
• Groups sync to reusable Cloudflare Access policies.
• Services map to Access applications using consistent naming and update logic.
• Public and authenticated patterns are supported through policy decisions.
• Zone-level defaults can be used to protect wildcard domains and reduce accidental exposure.

For one-off services, individual dockflare.access.* labels are still supported.

Example Labels

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

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"
      - "dockflare.access.email=admin@example.com,@example.com"

Reliability and Drift Management

• DockFlare reconciliation is designed to be idempotent.
• Runtime and configuration state are persisted in encrypted files.
• Manual rule options are preserved and re-applied across restarts.
• Optional unmanaged-ingress-field preservation can keep Cloudflare-side values that DockFlare does not explicitly model.
• Backup and restore enable rapid recovery of full control-plane state.

Security Model

• Supports web authentication with local credentials and OAuth providers.
• Uses scoped Cloudflare API tokens.
• Encourages Docker socket proxy for least-privilege Docker API exposure.
• Runs containers as non-root (UID/GID 65532) in the reference setup.
• Supports agent API key lifecycle controls and enrollment flow.

Operations and Day-2 Tasks

Common workflows handled in UI:

• Add, edit, and remove manual routes.
• Assign or change Access Groups on services.
• View service status and reconciliation state.
• Rotate or revoke agent API keys.
• Trigger agent tunnel actions.
• Export and restore backups.

Troubleshooting Pointers

• Verify Cloudflare token scopes first when API calls fail.
• Confirm domain-to-zone mapping when records do not appear.
• Validate service URL format (http:// or https://) for manual rules.
• Check agent heartbeat and enrollment status for remote hosts.
• Confirm Docker socket proxy permissions if container discovery fails.

Additional troubleshooting references:

• Common Issues
• Container Labels
• Multi-Server Agent

Development

• Build and run locally:

docker compose build --no-cache
docker compose up -d

• Basic health checks:

curl http://localhost:5000/ping
curl http://localhost:5000/api/v2/overview

Documentation Map

• Product docs: https://dockflare.app/docs
• Source docs in repository:
  • Multi-Server Agent Guide
  • Using the Web UI
  • Managing DNS Zones
  • Identity Providers

Changelog

Release notes are maintained in CHANGELOG.md.