Debugging&Logs.md

Troubleshooting: Debugging & Logs

When issues arise, checking DockFlare's logs is the most crucial step in diagnosing the problem.

Accessing Logs

There are two primary ways to view logs:

1. Web UI Real-time Log Stream:

   • Navigate to the DockFlare Web UI (e.g., http://localhost:5000).
   • Scroll down to the "Real-time Activity Logs" section.
   • Logs will stream directly in the browser as events happen.
   • Pros: Convenient, real-time view without needing terminal access.
   • Cons: Only shows logs generated since the UI page was loaded; relies on SSE working correctly.

2. Docker Container Logs:

   • Use the standard Docker command to view the container's stdout/stderr logs.
   • Open a terminal on your Docker host and run:

     docker logs dockflare

   • To follow the logs in real-time (like tail -f):

     docker logs -f dockflare

   • To view the last N lines:

     docker logs --tail 100 dockflare

   • Pros: Access to all historical logs since the container started; works even if the Web UI or SSE is having issues.
   • Cons: Requires terminal access to the Docker host.

What to Look For in Logs

• Initialization: Successful connection to Docker API, Cloudflare API. Tunnel creation/verification messages. Agent start messages (in Internal Mode). Reconciliation start/completion.
• Container Events: Logs indicating detection of container start/stop events (e.g., Detected container start: <container_id>).
• Label Processing: Messages showing labels being read and processed (e.g., Processing labels for container <container_id>). Indication of required labels found (enable, hostname, service).
• DNS Operations: Logs related to creating or deleting CNAME records (e.g., Creating DNS record for hostname.example.com, Deleting DNS record...). Look for success or error messages.
• Tunnel Configuration: Logs about updating the Cloudflare Tunnel ingress rules (e.g., Updating tunnel config with rule for hostname.example.com).
• Grace Period: Messages when a rule is marked for deletion and when the grace period expires and deletion is triggered.
• Errors: Pay close attention to any lines containing ERROR, WARNING, Traceback, or specific HTTP error codes (like 400, 401, 403, 429) from the Cloudflare API. These often pinpoint the exact problem (e.g., invalid API token, missing permissions, rate limiting, malformed hostname/service).

Common Debugging Steps

1. Check Logs First: Always start by examining the logs for explicit error messages.
2. Verify Configuration: Double-check your .env file (API token, account/zone IDs, tunnel name/ID) and container labels for typos or incorrect values.
3. Check API Token Permissions: Go to your Cloudflare dashboard -> My Profile -> API Tokens. Verify the token used by DockFlare has the exact required permissions: Zone:DNS:Edit and Account:Cloudflare Tunnel:Edit. Create a new token if unsure.
4. Test Cloudflare Connectivity: Use the /cloudflare-ping Health Check endpoint (if accessible) or manually verify Cloudflare API access from the host if possible.
5. Simplify: If multiple rules are failing, try reducing complexity. Stop all labeled containers except one simple test case. See if that one works.
6. Force Delete: If a rule seems stuck or incorrectly configured, try using the "Force Delete" button in the Web UI for that specific rule, then restart the corresponding application container to let DockFlare recreate it.
7. Restart DockFlare: A simple restart can sometimes resolve transient issues: docker restart dockflare.
8. Reset State (Last Resort): If you suspect corrupted state, follow the steps in State Persistence to reset the state.json file (requires stopping DockFlare and removing the volume/file).