ExternalcloudflaredMode.md

External cloudflared Mode

DockFlare can integrate with an existing, independently managed cloudflared agent instead of managing its own. This is known as "External Mode".

Use Cases

• You already have a cloudflared service running (e.g., as a systemd service, or a Docker container managed separately).
• You want multiple applications or controllers (including DockFlare) to add rules to the same Cloudflare Tunnel.
• You require specific cloudflared configurations or command-line arguments not exposed by DockFlare's internal management.

How it Works

In External Mode, DockFlare's responsibilities are reduced:

• DockFlare DOES:
  • Monitor Docker container events and labels.
  • Create/Delete CNAME DNS records in Cloudflare pointing to your existing tunnel's public address (<your-tunnel-id>.cfargotunnel.com).
  • Update the ingress rules within the configuration of your existing Cloudflare Tunnel via the Cloudflare API.
• DockFlare DOES NOT:
  • Create a Cloudflare Tunnel resource.
  • Generate tunnel credentials (tokens).
  • Run or manage the cloudflared agent container/process.

You are responsible for ensuring your external cloudflared agent is running correctly, connected to Cloudflare, and configured to read its ingress rules from the Cloudflare API / Dashboard (this is the default behavior for tunnels managed via the API/Dashboard).

Configuration

To enable External Mode, set the following environment variables for DockFlare:

1. USE_EXTERNAL_CLOUDFLARED=true: This flag activates the mode.
2. EXTERNAL_TUNNEL_ID=your-tunnel-id-from-cloudflare: This is the crucial piece – you must provide the unique ID (UUID) of the existing tunnel you want DockFlare to manage rules for.

Example .env snippet:

USE_EXTERNAL_CLOUDFLARED=true
EXTERNAL_TUNNEL_ID=6ff42ae2-765d-4adf-befc-ca51f8e4e688 # Replace with your actual Tunnel ID
# TUNNEL_NAME is IGNORED in this mode

# Other required variables like CF_API_TOKEN, CF_ACCOUNT_ID, CF_ZONE_ID are still needed!
CF_API_TOKEN=your_cloudflare_api_token_here
CF_ACCOUNT_ID=your_cloudflare_account_id_here
CF_ZONE_ID=your_cloudflare_zone_id_here

Finding Your Tunnel ID

If you don't know the ID of your existing tunnel:

1. Log in to your Cloudflare Dashboard.
2. Navigate to Zero Trust in the left sidebar.
3. Go to Access -> Tunnels.
4. Find your desired tunnel in the list and click on its name.
5. The Tunnel ID (a UUID like 6ff42ae2-765d-4adf-befc-ca51f8e4e688) is displayed prominently on the tunnel's overview page.
6. You can also find it in the URL of the tunnel's page: https://dash.cloudflare.com/[account-tag]/access/tunnels/edit/[tunnel-id]
7. Copy this ID and use it for the EXTERNAL_TUNNEL_ID environment variable.

Important Considerations

• Ensure your external cloudflared agent is running and healthy. DockFlare will configure rules, but they won't work if the tunnel connection itself is down.
• The Cloudflare API Token used by DockFlare still needs Account:Cloudflare Tunnel:Edit and Zone:DNS:Edit permissions to modify the external tunnel's config and manage DNS.
• If you need to switch from Internal Mode to External Mode, follow the cleanup steps outlined in Switching Between Modes.