EnvironmentVariables.md

Environment Variables

DockFlare is configured primarily through environment variables. These can be set directly in your docker run command or, more commonly, using an .env file alongside your docker-compose.yml.

Variable	Description	Default	Required?
Cloudflare Credentials
CF_API_TOKEN	Your Cloudflare API token. Must have Zone:DNS:Edit and Account:Cloudflare Tunnel:Edit permissions.	(None)	Yes
CF_ACCOUNT_ID	Your Cloudflare Account ID. Found on your main Cloudflare dashboard URL.	(None)	Yes
CF_ZONE_ID	The Zone ID of your primary domain. Used for DNS records if a container label doesn't specify a different zonename.	(None)	Yes
Internal (Managed) Mode	These are used when DockFlare manages the cloudflared agent.
TUNNEL_NAME	The name for the Cloudflare Tunnel that DockFlare will create and manage.	dockflare-tunnel	Yes (unless in External Mode)
CLOUDFLARED_IMAGE	The Docker image to use for the managed cloudflared agent.	cloudflare/cloudflared:latest	No
CLOUDFLARED_NETWORK_NAME	The Docker network to attach the managed agent to. Must be the same network as your target services.	cloudflare-net	No
External Mode	These are used when you manage the cloudflared agent yourself.
USE_EXTERNAL_CLOUDFLARED	Set to true to enable External Mode.	false	No
EXTERNAL_TUNNEL_ID	The UUID of the existing Cloudflare Tunnel to manage when in External Mode.	(None)	Yes (if USE_EXTERNAL_CLOUDFLARED=true)
Behavior & Scanning
LABEL_PREFIX	The prefix for Docker labels that DockFlare monitors. The trailing dot is optional.	dockflare	No
GRACE_PERIOD_SECONDS	Time (in seconds) to wait before deleting rules after a container stops. Prevents downtime during restarts.	3600 (1 hour)	No
CLEANUP_INTERVAL_SECONDS	How often (in seconds) DockFlare checks for expired rules to delete.	300 (5 minutes)	No
SCAN_ALL_NETWORKS	If true, DockFlare scans containers across all Docker networks, not just its own.	false	No
TUNNEL_DNS_SCAN_ZONE_NAMES	A comma-separated list of additional zone names to scan when viewing DNS records for tunnels in the UI.	(None)	No
Performance & Tuning
AGENT_STATUS_UPDATE_INTERVAL_SECONDS	How often (in seconds) the agent's status is checked and updated in the UI.	10	No
MAX_CONCURRENT_DNS_OPS	Maximum number of simultaneous DNS operations allowed. Helps prevent API rate-limiting.	3	No
RECONCILIATION_BATCH_SIZE	Number of containers to process in each batch during the initial startup scan.	5	No
Advanced/Internal
STATE_FILE_PATH	The path inside the container where the state.json file is stored.	/app/data/state.json	No
DEFAULT_NO_TLS_VERIFY	Sets the global default for whether to verify the TLS certificate of origin services. Can be overridden per rule.	false	No
TRUSTED_PROXIES	A comma-separated list of trusted proxy IPs/CIDR ranges for secure request handling.	(None)	No
TZ	Your local timezone (e.g., America/New_York) to ensure correct log timestamps.	(None)	No

Example .env File

# --- Required Settings ---
CF_API_TOKEN=your_cloudflare_api_token_here
CF_ACCOUNT_ID=your_cloudflare_account_id_here
CF_ZONE_ID=your_cloudflare_zone_id_here

# --- Configuration for Internal (Managed) Mode ---
TUNNEL_NAME=my-dockflare-tunnel
CLOUDFLARED_NETWORK_NAME=cloudflare-net

# --- Optional Customizations ---
# Use a custom label prefix (e.g., 'cf.ingress.')
LABEL_PREFIX=dockflare
# Set a 10-minute grace period
GRACE_PERIOD_SECONDS=600
# Set your timezone
TZ=America/New_York

# --- Example for External Mode (mutually exclusive with Internal Mode settings) ---
# USE_EXTERNAL_CLOUDFLARED=true
# EXTERNAL_TUNNEL_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx