Skip to content

Switching‐Between‐Modes.md

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

Switching Between Modes

Switching between DockFlare's Internal (managed) and External cloudflared modes is an advanced operation that requires manual steps to ensure a clean transition.

Caution

ADVANCED USERS ONLY - PROCEED WITH CAUTION

Switching modes is not an automated process. It requires manual cleanup of resources on both your Docker host and the Cloudflare dashboard. Failure to follow these steps can result in orphaned configurations, conflicting DNS records, and services being unreachable.

The safest path is always to ensure a clean state. Before proceeding, please read the External cloudflared Mode guide to fully understand its requirements.

Switching from Internal to External Mode

Follow these steps if you are currently using DockFlare's managed agent and want to switch to using your own externally managed cloudflared instance.

Goal: Stop using the DockFlare-managed agent and tunnel, and have DockFlare manage rules for your own pre-existing tunnel.

Step 1: Prepare Your External Tunnel

Before changing DockFlare, ensure your external cloudflared agent is fully configured, running, and connected to Cloudflare. You will need its Tunnel ID (UUID) for the next steps.

Step 2: Stop DockFlare

Bring your entire DockFlare stack down completely.

docker compose down

Step 3: Update DockFlare's Configuration

Edit your .env file to enable external mode:

  1. Set USE_EXTERNAL_CLOUDFLARED=true.
  2. Set EXTERNAL_TUNNEL_ID to the UUID of your existing tunnel.
  3. You can now remove or comment out the TUNNEL_NAME variable, as it will be ignored.

Step 4: Clean Up Old Internal Mode Resources

This is the most critical step to prevent conflicts.

  1. Remove the Managed Agent Container: DockFlare created an agent container (e.g., cloudflared-agent-dockflare-tunnel). While docker compose down should remove it, you can ensure it's gone by checking docker ps -a.
  2. (Optional but Recommended) Delete the Old Managed Tunnel: Log in to the Cloudflare Zero Trust dashboard, navigate to Access -> Tunnels, and delete the old tunnel that DockFlare was managing. This keeps your account clean. All DNS records pointing to it will become stale.
  3. Delete Local State: You must remove the old state.json file, as it contains references to the old managed tunnel. 
    # Replace 'dockflare_data' with your actual volume name if different
docker volume rm dockflare_data

Step 5: Start DockFlare

Now, start DockFlare with the new configuration.

docker compose up -d

Step 6: Verify

  • Check the DockFlare logs. You should see it running in External Mode.
  • DockFlare will not create a cloudflared-agent container.
  • It will begin reconciling your labeled containers and creating new DNS records that point to your new external tunnel ID.

Switching from External to Internal Mode

Follow these steps if you are currently using External Mode and want to switch to letting DockFlare manage the agent for you.

Goal: Stop using your own agent and have DockFlare create and manage a new tunnel and agent container from scratch.

Step 1: Stop Your External Agent

First, stop your manually managed cloudflared process or container. This is important to prevent two tunnels from being active.

Step 2: Stop DockFlare

Bring your entire DockFlare stack down.

docker compose down

Step 3: Update DockFlare's Configuration

Edit your .env file to enable internal mode:

  1. Set USE_EXTERNAL_CLOUDFLARED=false or remove the line entirely.
  2. Set a TUNNEL_NAME for the new tunnel DockFlare will create (e.g., TUNNEL_NAME=dockflare-managed-tunnel).
  3. You can now remove or comment out EXTERNAL_TUNNEL_ID.

Step 4: Clean Up Old External Mode Resources

  1. Delete Old DNS Records: Log in to your Cloudflare DNS dashboard and delete the CNAME records that were pointing to your old external tunnel. DockFlare will create new ones pointing to the new managed tunnel.
  2. Delete Local State: You must remove the old state.json file to clear any references to the old external tunnel ID. 
    # Replace 'dockflare_data' with your actual volume name if different
docker volume rm dockflare_data

Step 5: Start DockFlare

Start DockFlare with the new configuration.

docker compose up -d

Step 6: Verify

  • Check the DockFlare logs. You should see it creating a new tunnel with the name you provided.
  • Check docker ps. You should see a new cloudflared-agent-... container created and running.
  • DockFlare will create new DNS records for your services pointing to this new managed tunnel.
Clone this wiki locally