Skip to content

Quick‐Start‐Docker‐Compose.md

Jump to bottom
Chris edited this page Jun 22, 2025 · 11 revisions

Quick Start (Using Docker Compose)

This guide provides the quickest way to get DockFlare running using Docker Compose.

1. Create docker-compose.yml

Create a file named docker-compose.yml with the following content. This defines the DockFlare service, its network, and a volume for persistent state.

version: '3.8'

services:
  dockflare:
    image: alplat/dockflare:stable
    container_name: dockflare
    restart: unless-stopped
    # The Web UI port. You can change the host port if 5000 is in use.
    ports:
      - "5000:5000"
    # This file contains your Cloudflare credentials and settings.
    env_file:
      - .env
    environment:
      # Set your local timezone to see correct timestamps in the logs.
      - TZ=Europe/Zurich
    volumes:
      # Required to monitor Docker start/stop events.
      - /var/run/docker.sock:/var/run/docker.sock:ro
      # Persistent storage for state.json, which holds manual rules and UI overrides.
      - dockflare_data:/app/data
    networks:
      # This is the network DockFlare uses to communicate with the managed
      # cloudflared agent and any other services you want to expose.
      - cloudflare-net
    # Optional: Expose the DockFlare UI itself through the tunnel.
    # Remember to configure an Access Policy to secure it!
    labels:
      - "dockflare.enable=true"
      - "dockflare.hostname=dockflare.yourdomain.tld" # <-- Update with your domain
      - "dockflare.service=http://dockflare:5000"
      - "dockflare.access.policy=authenticate" # <-- Example: secure with Cloudflare Access

volumes:
  dockflare_data:
    name: dockflare_data

networks:
  cloudflare-net:
    name: cloudflare-net

Note: The labels on the dockflare service are optional but recommended. They demonstrate how to expose a service—in this case, the DockFlare UI itself. Make sure to choose a secure access.policy if you use them.

2. Create .env File

Create a file named .env in the same directory. This file stores your sensitive credentials and configuration settings.

Replace the placeholder values with your actual Cloudflare details.

# --- Required Settings ---

# Cloudflare API Token with necessary permissions (see Prerequisites).
CF_API_TOKEN=your_cloudflare_api_token

# Your Cloudflare Account ID (found on your main Cloudflare dashboard).
CF_ACCOUNT_ID=your_cloudflare_account_id

# The Zone ID for the domain you want to use.
CF_ZONE_ID=your_cloudflare_zone_id

# --- Tunnel Configuration (Managed Mode) ---

# A name for the tunnel DockFlare will create and manage.
TUNNEL_NAME=dockflare-tunnel

# The name of the Docker network for the managed cloudflared agent.
# This MUST match the network in your docker-compose.yml.
CLOUDFLARED_NETWORK_NAME=cloudflare-net

# --- Optional Settings ---

# The label prefix DockFlare looks for. Defaults to "dockflare.".
# Set to "cloudflare.tunnel" for legacy compatibility if needed.
# LABEL_PREFIX=dockflare.

# Grace period in seconds before a rule is deleted after a container stops.
GRACE_PERIOD_SECONDS=3600

# You generally do not need to change the settings below this line.
# ----------------------------------------------------------------
CLEANUP_INTERVAL_SECONDS=300
AGENT_STATUS_UPDATE_INTERVAL_SECONDS=10
SCAN_ALL_NETWORKS=false
MAX_CONCURRENT_DNS_OPS=3
RECONCILIATION_BATCH_SIZE=3
# For advanced proxy setups, e.g. TRUSTED_PROXIES=172.16.0.0/12
# TRUSTED_PROXIES=
DEFAULT_NO_TLS_VERIFY=false
STATE_FILE_PATH=/app/data/state.json

Important: Ensure the .env file is protected and not committed to public repositories.

3. Run DockFlare

Navigate to the directory containing your docker-compose.yml and .env files in your terminal and run:

docker compose up -d

This command will:

  • Pull the alplat/dockflare:stable image.
  • Create the cloudflare-net network if it doesn't exist.
  • Create the dockflare_data volume for persistent state.
  • Start the dockflare container in detached mode (-d).

DockFlare will now start up. In the background, it will:

  1. Connect to Cloudflare and create (or find) the tunnel named dockflare-tunnel.
  2. Create and start a new container named cloudflared-agent-dockflare-tunnel.
  3. Begin listening for other containers on your system with the dockflare.enable="true" label.

Next Steps

Clone this wiki locally