DockFlare README

The project's README from github.com/ChrispyBacon-dev/DockFlare. As one markdown file: README.md.

DockFlare Logo

Automate Cloudflare Tunnels with Docker Labels

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

Stars Release Docker Pulls Python License Swiss Made

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 with a fully localized native experience: less operational drift, more reliable service exposure, and one place to manage routing and access decisions.

Core Capabilities

Architecture Overview

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

Component Purpose
DockFlare Master Web UI, encrypted config/state, reconciliation, Cloudflare API orchestration
DockFlare Mail Manager Sovereign email backend, SQLite storage, R2 integration, and webhook handling
DockFlare Webmail PWA-ready mail client with push notification support
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, Email, 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

One-Liner Install

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

The script will guide you through:

  1. Choosing an install directory (default: ~/dockflare/).
  2. Choosing a local UI port (default: 5000).
  3. Optionally configuring a Cloudflare Tunnel for DockFlare itself.
  4. Optionally enabling the Email profile (dockflare-mail-manager + dockflare-webmail).

For full setup documentation, use the project docs site:

Prerequisites

Cloudflare API Permissions

Quick Start Docker Compose

Before first launch, create the shared network once:

docker network create cloudflare-net
  1. Create docker-compose.yml:
services:
  docker-socket-proxy:
    image: tecnativa/docker-socket-proxy:v0.4.1
    container_name: docker-socket-proxy
    restart: unless-stopped
    logging:
      driver: "none"
    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" # Optional: comment out once exposed via Cloudflare Tunnel with an Access Policy to restrict access to tunnel-only
    #labels: # -- Cloudflare Tunnel Configuration (via DockFlare) OPTIONAL --
      # Main DockFlare with access policy
      #- dockflare.enable=true
      #- dockflare.hostname=dockflare.TLD  # replace with your domain
      #- dockflare.service=http://dockflare:5000
      #- dockflare.access.group=YOUR-ACCESS-GROUP-ID  # your custom access policy
      # -- OAuth Callback Path (Bypass Access Policy) OPTIONAL --
      # Required if using OAuth authentication with access policies on main interface
      #- dockflare.0.hostname=dockflare.example.tld
      #- dockflare.0.path=/auth/google/callback
      #- dockflare.0.service=http://dockflare:5000
      #- dockflare.0.access.group=public-default-bypass

      # Add additional callback paths for other OAuth providers as needed
      # - dockflare.1.hostname=dockflare.example.com
      # - dockflare.1.path=/auth/github/callback
      # - dockflare.1.service=http://dockflare:5000
      # - dockflare.1.access.group=public-default-bypass
    volumes:
      - dockflare_data:/app/data
    environment:
      - REDIS_URL=redis://redis:6379/0
      - REDIS_DB_INDEX=0
      - 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"]
    logging:
      driver: "none"
    volumes:
      - dockflare_redis:/data
    networks:
      - dockflare-internal

  dockflare-mail-manager:
    image: alplat/dockflare-mail-manager:stable
    container_name: dockflare-mail-manager
    restart: unless-stopped
    profiles: ["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

  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:
      - 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
  dockflare-internal:
    name: dockflare-internal
  1. Start DockFlare:
docker compose up -d

The Email Suite is an optional, opt-in feature and will not start by default. To include email services, add the email profile:

docker compose --profile email up -d

Email setup and provisioning guide: Email Overview

  1. 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

Agent source and standalone deployment files: dockflare-agent/

Access Control Model

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

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"
      - "[email protected],@example.com"

Reliability and Drift Management

Security Model

Operations and Day-2 Tasks

Common workflows handled in UI:

Troubleshooting Pointers

Additional troubleshooting references:

Development

docker compose build --no-cache
docker compose up -d
curl http://localhost:5000/ping
curl http://localhost:5000/api/v2/overview

Documentation Map

(Available in 8 languages directly within the DockFlare UI or online)

Changelog

Release notes are maintained in CHANGELOG.md. ailable in 8 languages directly within the DockFlare UI or online)*

Changelog

Release notes are maintained in CHANGELOG.md.

DockFlare (ChrispyBacon-dev/DockFlare)

Searching Database…

What is this?DockFlare automates Cloudflare Tunnel setup for self-hosted services. It reads Docker labels and reconciles DNS records, tunnel ingress rules, and Cloudflare Access apps, so you don't have to configure them by hand in the Cloudflare dashboard.
Is it an app I run or a library I add to my code?It's an app, not a library. It runs as a Docker Compose stack with a web UI, a Redis instance, and optional email and agent components.
How do I get it running?Create the shared Docker network once, then run the one-liner install script. It asks for an install directory (default ~/dockflare/), a UI port (default 5000), and optional Cloudflare Tunnel and Email profile setup. Finish in the setup wizard in your browser.
What do I need before starting?Docker with Docker Compose, a Cloudflare account, your Account ID and primary Zone ID, and an API token with the listed scopes (Tunnel, Access, DNS). Email features need extra Workers, R2, and Email Routing scopes. Redis is included in the quick-start stack.
What's the most common pitfall?API token scopes. The README says to check token permissions first when API calls fail, so it's worth getting the token right before the first launch.
Is it meant for a home lab or for a company?It's built for fast-changing self-hosted environments such as home labs. Multi-host setups with agents also work for small teams running several Docker hosts.
What is the Email Suite, and do I need it?It's an optional, opt-in profile that adds a self-hosted email system on Cloudflare Email Routing. It supports multiple domains and includes an installable Vue 3 webmail client. It doesn't start unless you enable the email profile.
How do I expose a Docker service with labels?Add labels to the container that declare the hostname, service target, and access behavior. DockFlare then creates the DNS record and ingress rule automatically.
Can it expose things that aren't in Docker?Yes. Manual rules in the web UI cover static hosts, VMs, appliances, and external services. Hybrid mode merges them with label-based routes into one reconciliation model.
What are Access Groups for?A group is a reusable access policy that can be attached to several services. Zone-level defaults help protect wildcard domains from accidental exposure.
Size
33.9 MB
Stars
2.5K
Age
1y
Commits · 90 Days