DockFlare README

README проекта с github.com/ChrispyBacon-dev/DockFlare. Одним файлом markdown: 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)

Ищем в базе…

Что это такое?DockFlare автоматизирует настройку Cloudflare Tunnel для самостоятельно размещаемых сервисов. Он читает метки Docker и синхронизирует DNS-записи, правила входящего трафика туннеля и приложения Cloudflare Access, так что не нужно настраивать их вручную в панели Cloudflare.
Это приложение, которое я запускаю, или библиотека, которую добавляю в код?Это приложение, а не библиотека. Оно работает как стек Docker Compose с веб-интерфейсом, экземпляром Redis и необязательными компонентами для почты и агентов.
Как его запустить?Один раз создайте общую сеть Docker, затем запустите установочный скрипт в одну строку. Он спросит каталог установки (по умолчанию ~/dockflare/), порт веб-интерфейса (по умолчанию 5000) и, если нужно, настройку профилей Cloudflare Tunnel и почты. Завершите настройку в мастере в браузере.
Что нужно подготовить перед началом?Docker с Docker Compose, аккаунт Cloudflare, ваш Account ID и основной Zone ID, а также API-токен с перечисленными правами (Tunnel, Access, DNS). Для функций почты нужны дополнительные права Workers, R2 и Email Routing. Redis входит в стек быстрого старта.
Какая самая частая ошибка?Права API-токена. В README сказано в первую очередь проверять права токена, если вызовы API не работают, поэтому стоит правильно настроить токен до первого запуска.
Это для домашней лаборатории или для компании?Он создан для быстро меняющихся самостоятельно размещаемых сред, например домашних лабораторий. Конфигурации с несколькими хостами и агентами тоже подходят небольшим командам, которые управляют несколькими хостами Docker.
Что такое Email Suite и нужен ли он мне?Это необязательный профиль, который включается вручную. Он добавляет самостоятельно размещаемую почтовую систему на базе Cloudflare Email Routing. Поддерживает несколько доменов и включает устанавливаемый веб-клиент почты на Vue 3. Без включения почтового профиля он не запускается.
Как открыть сервис Docker с помощью меток?Добавьте к контейнеру метки, в которых указаны имя хоста, цель сервиса и правила доступа. Затем DockFlare автоматически создаст DNS-запись и правило входящего трафика.
Можно ли открыть то, чего нет в Docker?Да. Ручные правила в веб-интерфейсе подходят для статических хостов, виртуальных машин, устройств и внешних сервисов. Гибридный режим объединяет их с маршрутами на основе меток в единую модель согласования.
Для чего нужны Access Groups?Группа — это многоразовая политика доступа, которую можно привязать к нескольким сервисам. Настройки по умолчанию на уровне зоны помогают защитить wildcard-домены от случайного открытия.
Размер
33.9 MB
Звёзды
2.5K
Возраст
1 г
Коммиты · 90 дней