Skip to content

InternalvsExternalcloudflared.md

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

Internal vs External cloudflared Mode

DockFlare can operate in two distinct modes regarding the cloudflared agent—the software that establishes the secure connection to Cloudflare's edge network.

1. Internal Mode (Default & Recommended)

In this mode, DockFlare takes full responsibility for the cloudflared agent's entire lifecycle. It provides a "batteries-included" experience.

  • How it Works:

    1. DockFlare creates a Cloudflare Tunnel resource on your account using the TUNNEL_NAME you provide.
    2. It securely retrieves that tunnel's unique credentials (the Tunnel Token).
    3. It deploys and runs a dedicated cloudflared Docker container, passing it the token to establish the connection.
    4. Crucially, DockFlare continuously reconciles this agent. On startup, it checks if the agent's configuration (like its network or image version) matches your .env settings and automatically recreates it if there's a mismatch. This ensures your configuration changes are always applied.
    5. DockFlare then manages the ingress rules for this tunnel.

  • Configuration:

    • USE_EXTERNAL_CLOUDFLARED=false (or simply omit the variable).
    • TUNNEL_NAME environment variable is required.

  • Pros:

    • Easiest Setup: The simplest way to get started. DockFlare handles everything.
    • Self-Contained & Automated: No need to manually manage a separate cloudflared instance or worry about configuration drift.

  • Cons:

    • Creates a dedicated tunnel for DockFlare's services. If you have complex, pre-existing tunnel setups, External Mode might be a better fit.

2. External Mode

In this mode, you manage the cloudflared agent yourself, and DockFlare acts purely as a configuration controller for that existing tunnel.

  • How it Works:

    1. You must have an existing Cloudflare Tunnel already created.
    2. You are responsible for running the cloudflared agent process (e.g., as a system service or another Docker container) and keeping it connected to Cloudflare.
    3. DockFlare uses the Cloudflare API to add, update, and remove ingress rules and DNS records for the existing tunnel you specify.
    4. DockFlare does not create a tunnel or manage any cloudflared agent container itself.

  • Configuration:

    • USE_EXTERNAL_CLOUDFLARED=true is required.
    • EXTERNAL_TUNNEL_ID is required. You must provide the UUID of your existing tunnel.
    • TUNNEL_NAME is ignored.

  • Pros:

    • Allows integration with pre-existing cloudflared deployments.
    • Enables sharing a single tunnel across multiple applications or controllers.
    • Gives you full, manual control over the cloudflared agent's deployment.

  • Cons:

    • More Complex Setup: You are responsible for the tunnel and agent's operational state.
    • Requires you to find and provide the EXTERNAL_TUNNEL_ID.

Which Mode Should You Choose?

  • Use Internal Mode if:

    • You are new to Cloudflare Tunnels and want the easiest, most automated setup.
    • You want a dedicated, self-managing tunnel for the services DockFlare exposes.
    • This is the recommended mode for most users.

  • Use External Mode if:

    • You are an advanced user with an existing cloudflared tunnel you want to integrate with.
    • You have a specific reason to manage the cloudflared agent's lifecycle separately from DockFlare.

See Also:

Clone this wiki locally