Restructure Troubleshooting into a hub with per-area pages (#814)

* Restructure Troubleshooting into a hub with per-area pages

- Add a Troubleshooting hub (/help/troubleshooting) with icon/chip cards and a "Still stuck?" CTA
- Split NetBird Client troubleshooting into an overview + per-OS pages (Linux, Windows, macOS, Android, iOS)
- Split Self-hosted troubleshooting into an overview + per-area pages (installation, IdP, dashboard, certificates, connectivity, database)
- Split "Report bugs and issues" into Community Support and NetBird Support pages
- Add Troubleshooting resource connectivity and a NetBird Cloud pending-approval page
- Add DNS troubleshooting Issue 8 (Windows NRPT rule blocked by a lingering GPO)
- Cross-reference the new pages from networks, DNS, and reverse-proxy docs; update nav

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Address review: client terminology, dead props, labels, cross-links

- Use "client" instead of "agent" across the client troubleshooting pages (headings, prose, anchors)
- Remove unused source: props from the Troubleshooting hub tiles
- Relabel the "NetBird Cloud" grouping to "Cloud & identity" (SSO/provisioning also apply to self-hosted)
- Add a Tiles title on the report-bug landing; add reverse-proxy -> resource-connectivity cross-link
- Fix comma splices introduced by the em-dash cleanup in relayed-connections

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Add client-side hash redirect for moved self-hosted anchors

Old deep links like /selfhosted/troubleshooting#debugging-turn-connections now
forward to the per-area page, since next.config redirects can't act on the URL fragment.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Apply docs-skill review: conventions + reshape area pages

- "open source" (no hyphen), expand NRPT on first use, descriptive alt text + captions on TURN images
- Fix inherited "Netbird" casing in the client glossary
- Reshape the six self-hosted area pages to Symptom -> likely causes (ordered) -> Fix -> Confirm, preserving anchored headings

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Fix two typos in client glossary (CodeRabbit)

- "nunning" -> "running" in the glossary
- possessive "it's" -> "its" in the routing-table sentence

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: fix two broken links in troubleshooting pages

- database: point the "upgrade path" link at /selfhosted/maintenance/upgrade;
  selfhosted-quickstart has no #upgrade anchor so the old link landed at page top
- client: add HashRedirect so old #net-bird-agent-status deep links forward to
  the renamed #net-bird-client-status section on the same page

* docs: address review follow-ups (deep-link redirects + client casing)

- self-hosted troubleshooting: extend the HashRedirect map with the per-issue
  (###-level) anchors from the old single page, so old deep links land on the
  exact sub-section of the new area page rather than just the page top
- client glossary: lowercase "NetBird client" in the peer-a/peer-b entries
  (house convention) and fix "linux" -> "Linux"

* docs: review polish — fix image class + first-use acronym glosses

- connectivity: fix bad CSS class imagewrapper-nig -> imagewrapper on the
  TURN-test screenshot (the typo'd class matched no style and broke zoom)
- gloss acronyms on first use: GPO (DNS Issue 8), IdP/SSO (identity-provider),
  ACME (certificates), CORS (dashboard)

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com>
This commit is contained in:
Bruno Mercier Costa
2026-06-26 15:42:59 +02:00
committed by GitHub
parent ffb72cfa34
commit 5729ad035e
32 changed files with 1792 additions and 475 deletions

View File

@@ -6,6 +6,8 @@ export const description = 'Troubleshoot common reverse proxy issues like 502 er
This guide helps you diagnose and resolve common reverse proxy issues in NetBird. Follow the structured approach below to identify and fix problems quickly.
If a service behind a routing peer is unreachable in general (not specific to the reverse proxy), see [Troubleshooting resource connectivity](/help/troubleshooting-resource-connectivity) to find which layer is dropping the traffic.
## Quick Diagnostics Checklist
Before diving deep, run through this quick checklist: