SwitchingBetweenModes.md

Switching Between Internal and External Cloudflared Modes

Changing DockFlare's operating mode (from managing its own cloudflared agent to using an external one, or vice-versa) requires careful steps to avoid conflicts and ensure a clean transition. This guide focuses on switching from Internal to External Mode. Switching the other way involves similar cleanup but targeting the external setup.

Warning: This process involves deleting Cloudflare resources and potentially resetting DockFlare's state. Your services exposed via the old tunnel will experience downtime during the transition until they are reconfigured on the new (external) tunnel. DNS propagation time also applies.

Steps to Switch from Internal to External Mode

1. Stop DockFlare: Prevent DockFlare from making further changes while you reconfigure.

   docker stop dockflare
   # Or if using docker-compose:
   # docker compose stop dockflare

2. Remove the Internal cloudflared Agent: DockFlare created a container for the agent. Find its name (usually cloudflared-agent-<TUNNEL_NAME>) and remove it. Replace your_tunnel_name with the actual TUNNEL_NAME used in your original .env file.

   # Find the exact name if unsure: docker ps -a | grep cloudflared
   docker rm -f cloudflared-agent-your_tunnel_name

3. Clean Up Cloudflare DNS Records: Log in to your Cloudflare Dashboard.

   • Navigate to the DNS settings for the zone(s) managed by DockFlare.
   • Find and delete the CNAME records created by DockFlare in Internal Mode. These records point to <internal-tunnel-id>.cfargotunnel.com. The hostnames will match the cloudflare.tunnel.hostname labels you used.

4. Delete the Internal Tunnel (Optional but Recommended): To avoid clutter and potential confusion, delete the tunnel resource created by DockFlare in Internal Mode.

   • In the Cloudflare Dashboard, go to Zero Trust -> Access -> Tunnels.
   • Find the tunnel matching the TUNNEL_NAME from your old .env file.
   • Click the three dots (...) menu next to the tunnel and select Delete. Confirm the deletion.

5. Reset DockFlare's State: To ensure DockFlare starts fresh and doesn't try to manage resources associated with the old internal tunnel, remove its persisted state.

   • If using the recommended Docker Compose volume mount:

     # Find the volume name if unsure (often projectname_dockflare_data)
     docker volume rm dockflare_data # Or your specific volume name

   • If you mounted a host directory for /app/data, delete the state.json file within that directory:

     # Example: rm /path/on/host/to/dockflare/data/state.json

6. Set Up Your External cloudflared:

   • Ensure you have an existing Cloudflare Tunnel created (or create a new one manually via Dashboard/CLI).
   • Note down its Tunnel ID (UUID). See Finding Your Tunnel ID.
   • Configure and run your external cloudflared agent (e.g., as a service, separate Docker container) ensuring it connects using the credentials for this external tunnel. Refer to Cloudflare's documentation.

7. Update DockFlare's .env File: Modify your .env file for External Mode.

   # Comment out or remove TUNNEL_NAME
   # TUNNEL_NAME=your_tunnel_name
   
   # Add External Mode configuration
   USE_EXTERNAL_CLOUDFLARED=true
   EXTERNAL_TUNNEL_ID=your_actual_external_tunnel_id_here # Paste the ID found in step 6
   
   # Keep other required variables
   CF_API_TOKEN=your_cloudflare_api_token
   CF_ACCOUNT_ID=your_cloudflare_account_id
   CF_ZONE_ID=your_cloudflare_zone_id
   # ... other optional vars ...

8. Restart DockFlare: Start DockFlare with the updated configuration.

   docker start dockflare
   # Or if you removed the container/volume:
   # docker compose up -d --force-recreate

9. Verify:

   • Check DockFlare's logs (via Web UI or docker logs dockflare) for successful initialization in External Mode.
   • Verify in the Web UI that your labeled containers are detected.
   • Check the Cloudflare Dashboard:
     • DNS records should be recreated, now pointing to your external tunnel's address (<external-tunnel-id>.cfargotunnel.com).
     • The external tunnel's configuration should show the new ingress rules added by DockFlare.
   • Test access to your services via their public hostnames. Allow time for DNS propagation.

After these steps, DockFlare will manage DNS and ingress rules for your existing external tunnel based on your container labels, without attempting to manage the agent itself.