Skip to main content

brain.id86.net Incident Report (Mermaid, Build Script, 502)

This report summarizes the issues found during troubleshooting and the fixes applied to restore service stability.

Environment Context​

  • Stack: Docusaurus in Docker, Cloudflare Zero Trust, Cloudflare Tunnel (cloudflared).
  • Site: brain.id86.net.
  • Primary app container: docusaurus.

Issues Found​

1) Mermaid parse errors in docs pages​

Error pattern observed:

Parse error ... got 'PS'

Root cause:

  • Mermaid edge labels containing option flags were unquoted (for example |-n|, |-a|, |--squash|), which can be tokenized incorrectly by Mermaid parser.

2) Forced build script failure (ENOTEMPTY) during build​

Error observed from build-if-changed.sh run:

ENOTEMPTY: directory not empty, rmdir '/app/build//docs/code/git-github/introduction'

Root cause:

  • Build reused an existing build/ tree and hit stale directory cleanup race/cleanup behavior in Docusaurus output removal.

3) Intermittent 502 on brain.id86.net​

Error observed in cloudflared logs:

dial tcp 172.20.0.8:3000: connect: connection refused

Root cause:

  • Container startup command for prod had been changed to build && serve, creating a startup window where port 3000 was not listening yet.
  • During that window, Cloudflare Tunnel forwarded requests and returned 502.

What Was Changed​

A) Mermaid syntax hardening​

Updated Mermaid labels to quoted strings in:

  • docs/server/linux-server/02-Navigation-and-Filesystem/Filesystem Operations/mv.mdx
  • docs/server/linux-server/02-Navigation-and-Filesystem/Filesystem Operations/touch.mdx
  • docs/code/git-github/04-branching-and-merging/merge-strategies.mdx

Example fix pattern:

B) Build script resilience improvement​

Updated:

  • /home/rezriz/github/01-production/docusaurus-build-if-changed/build-if-changed.sh
  • /home/rezriz/github/01-production/docusaurus-build-if-changed/README.md

Applied fix:

  • Added CLEAN_BUILD_OUTPUT (default 1) to clean build output before build.
  • Effective behavior: rm -rf build && npm run build.

Result:

  • Forced run completed successfully, build validated, and container restart completed.

C) 502 mitigation and service stability​

Updated:

  • package.json prod script back to serve-only:
"prod": "docusaurus serve --host 0.0.0.0 --port 3000"

Operational step:

  • Restarted docusaurus container.

Result:

  • Origin became reachable again on 172.20.0.8:3000.
  • brain.id86.net returned Cloudflare Access page instead of 502.

Validation Performed​

  • Checked container status with docker ps.
  • Checked docusaurus logs for serve/build runtime.
  • Checked cloudflared logs for origin connectivity errors.
  • Probed origin directly with:
curl -I http://172.20.0.8:3000/

Expected/observed:

  • No connection refused after final fix.
  • Tunnel no longer fails to connect to Docusaurus origin during steady state.

Final Status​

  • Mermaid parse errors resolved for affected docs.
  • build-if-changed.sh failure mode (ENOTEMPTY) resolved.
  • brain.id86.net 502 issue resolved by removing startup build window from production serve path.

Follow-Up Recommendations​

  1. Keep production startup as serve-only; run builds in deployment/pre-deploy jobs.
  2. Keep build-if-changed.sh as the build gate and scheduler entrypoint.
  3. Add optional healthcheck and readiness gating before exposing origin through tunnel.
  4. Periodically review cloudflared logs to separate unrelated service failures (for example n8n) from Docusaurus incidents.