Skip to main content

Cloudflare Tunnel 502 Recovery (brain.id86.net)

This document records exactly what was done to restore brain.id86.net after a 502 incident in a Docker + Cloudflare Tunnel + Zero Trust setup.

Incident Summary​

  • Symptom: brain.id86.net returned 502 Bad Gateway.
  • Tunnel log: Unable to reach the origin service ... connect: connection refused.
  • Affected origin mapping: brain.id86.net routed to http://docusaurus:3000.
  • Root behavior: docusaurus container was frequently unavailable during build/start cycles.

Root Causes Confirmed​

  1. docusaurus startup command performs full install/build on restart, causing long origin downtime.
  2. New WP-CLI cheatsheet docs had MDX table syntax errors, causing build failures/restarts.
  3. Tunnel pointed to the unstable origin (docusaurus) during recovery window.

What Was Fixed​

1) Fixed MDX syntax issues in cheatsheet docs​

Affected folder:

  • docs/wordpress/wp-cli/16. Cheatsheet

Actions:

  • Escaped angle bracket placeholders inside table cells (<...>).
  • Replaced pipe-style alternatives inside syntax strings (for example id|login) with safe text labels (id-or-login).
  • Removed invalid MDX patterns that broke parser/SSG.

Verification command used:

sudo docker exec docusaurus sh -lc 'cd /app && npm run build'

2) Cleared stale Docusaurus/Webpack build cache​

This removed stale references still pointing to old doc IDs.

sudo docker exec docusaurus sh -lc 'rm -rf /app/.docusaurus /app/node_modules/.cache'

3) Corrected tunnel ingress to a stable origin (temporary recovery path)​

File updated:

  • /opt/docker-data/tunnel/config/config.yml

Change applied:

  • brain.id86.net was kept on http://docusaurus:3000 after production stabilized.

Then reloaded tunnel:

sudo docker restart cloudflared

Validation After Recovery​

  • curl -I https://brain.id86.net returned Cloudflare Access redirect (302), not 502.
  • Cloudflare tunnel stopped reporting fresh Unable to reach origin errors for brain.id86.net after remap.
  • Site became reachable again through Zero Trust login flow.

Useful Commands Used During Incident​

# container status
sudo docker ps --format 'table {{.Names}}\t{{.Status}}'

# docusaurus logs
sudo docker logs --tail 200 docusaurus

# tunnel logs
sudo docker logs --tail 200 cloudflared

# inspect docusaurus process state
sudo docker exec docusaurus sh -lc 'ps -ef | grep -E "docusaurus|node|serve" | grep -v grep'

# test public endpoint
curl -I -m 15 https://brain.id86.net
  1. Change production docusaurus container strategy to avoid full build on every restart.
  2. Keep brain.id86.net mapped to the stable origin only after health checks pass.
  3. Run MDX/build validation before reload/restart during content migrations.
  4. Add a healthcheck and operational runbook for tunnel/origin failover.

Follow-Up: Production Route Confirmed​

After stability checks, ingress remained on production origin:

  • brain.id86.net -> http://docusaurus:3000