mirror of https://github.com/netbirdio/docs.git synced 2026-08-24 16:51:26 +02:00

Files

Jack Carter f403129f66 Navigation cleanup: MDM deployment under Peers, purge stale tutorials, MSP portal refresh (#906 )

* docs: move MDM deployment guides under Manage > Peers

The five fleet-deployment guides (GPO, macOS .pkg, Jamf Pro, Kandji,
Intune) lived under Integrations, but nothing in them integrates with
NetBird's platform — they are peer onboarding at scale, which lives
under Peers. The label also collided with Access Control's
'Integrate MDM & EDR', which uses MDM in the opposite sense.

- Move pages from /manage/integrations/mdm-deployment/ to
  /manage/peers/mdm-deployment/ with a permanent wildcard redirect
- Re-point legacy /how-to redirects directly at the new paths
- Move the nav group under Peers as 'MDM Deployment'; remove the
  now-empty Integrations group
- Update internal links

* docs: link full GPO deployment guide from MDM integration page

* docs: show setup-key secret wiring and replica naming for k8s routing peers

Fold the two verified-novel bits from the Access Infrastructure
autoscaling tutorial before purging it:

- Replace the 'use a secret' Note with the actual kubectl create
  secret + secretKeyRef wiring (matches what the NetBird operator
  injects for routing peers)
- In the HA section, note that removing the static NB_HOSTNAME lets
  each replica register under its pod name (client falls back to
  os.Hostname(), which is the pod name in Kubernetes)

* docs: purge redundant Access Infrastructure tutorials

The four pages under Manage > Peers > Access Infrastructure were
2024-era SEO tutorials that duplicated canonical feature docs and
carried outdated claims (pre-rewrite SSH model without the built-in
SSH server, a Docker section that never actually enrolls the
container with a setup key, CrowdStrike presented as the only EDR
integration, stale v0.29 output and vintage-UI screenshots).

Cross-checked each page against its canonical counterpart; nothing
novel remained (the two useful Kubernetes snippets were folded into
the routing-peers use case in the previous commit).

- Delete the four pages and their screenshot directory
- Remove the Access Infrastructure nav group
- Redirect each URL to its canonical replacement:
  secure-remote-webserver-access -> /manage/peers/ssh
  setup-keys-add-servers-to-network -> /manage/peers/register-machines-using-setup-keys
  access-internal-resources-from-autoscaled-environments -> /use-cases/kubernetes
  peer-approval-for-remote-worker-access -> /manage/peers/approve-peers
- Re-point the legacy /how-to redirects at the same targets to avoid
  redirect chains

* docs: reorder Peers nav into enrollment, approval, day-2 flow

Group the five enrollment methods first (Add Peers, Setup Keys,
Bootstrap via Config File, MDM Deployment, Browser Client), then the
Approve Peers admission gate, then running-peer features (SSH, Lazy
Connections, Remote Jobs) and Auto Update last. Approve Peers
previously sat between two enrollment pages.

* docs: cross-link DNS aliases and internal DNS pages, fix tutorial inaccuracies

The two pages solve adjacent problems (NetBird-hosted records vs
forwarding to existing internal DNS) but never pointed at each other.
Add a which-page-do-I-need Note to each.

Also fix defects in the DNS Aliases tutorial found while cross-checking
it against the Custom Zones reference and dashboard source:

- 'Keep this enabled' implied search domain is on by default; it is
  off by default (DNSZoneModal.tsx: enable_search_domain ?? false)
- Step 3 said 'wildcard resource' but the steps add exact-name domain
  resources
- Wrong alt text ('Delete DNS Zone') on the zone-config screenshot
- Add missing meta description and a link to the Custom Zones
  reference

* docs: align MSP portal page with 2026 partner program, rename For Partners nav

Cross-checked the MSP portal page against the 2026 MSP/MSSP Partner
Program document:

- Point the application link at netbird.io/use-cases/msp (the program's
  canonical page) instead of a demo-form URL displayed as netbird.io/msp
- State tenant plan options (Team or Business) and the post-trial
  minimum (Team plan with one user)
- Mention CSV/PDF usage export alongside the API
- Clarify the 3-day trial for existing accounts brought in as tenants:
  it is a window to subscribe the tenant under the MSP account
- Add a subtle msp@netbird.io contact line at the bottom

Also rename the For Partners nav entries by deliverable instead of
audience (the section header already says who it's for): MSP Portal,
Distributor Portal, Deploy with Acronis.

* docs: update CLAUDE.md for agent-network, proxy.js, and tooling gaps

Audited every claim against the current repo. Stack, routing, security,
and convention claims all still hold; four gaps had accumulated:

- Add agent-network/ to the content structure list
- Document src/proxy.js in URL Routing: /api data requests must be
  rewritten there because the config rewrite loses data-request context
  on client-side navigation (Next.js #39669) and strips pageProps
- Add npm run lint:mdx; note npm run gen requires a Go toolchain
- Note fenced mermaid code blocks render as diagrams

* docs: address review findings on PR #906

- Move the MDM deployment screenshot directories to match the new page
  paths; the URL rewrite had updated MDX image references without
  moving the assets, breaking all Intune/Jamf/Kandji images
- Normalize pre-existing double slashes in Jamf and Kandji image URLs
- Align the routing-peers secret example with bootstrap-via-config-file
  (same secret name, so both now use the NB_SETUP_KEY data key)
- DNS aliases: include the routing peer's group in the zone's
  distribution groups. Verified in client source: the DNS route
  interceptor (priority 100) outranks local zone records (priority 75)
  and never falls through, so clients forward routed-domain queries to
  the routing peer, which must receive the zone to answer

2026-08-07 14:37:41 +02:00

6.1 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Documentation website for NetBird, an open-source WireGuard-based Zero Trust Networking platform. Built with Next.js 16 (Pages Router), React 19, MDX, and Tailwind CSS 3. Requires Node.js >=20.9 — npm run build exits with code 1 on older versions.

There is no test suite in this project. Validate changes with npm run build.

package-lock.json is committed, so installs are pinned. When you change dependencies in package.json, regenerate the lockfile (npm install) and commit it in the same change — otherwise local, CI, and Docker builds resolve different trees.

Common Commands

npm install              # Install dependencies
npm run dev              # Start dev server (also runs gen:edit-routes, gen:last-updated, gen:sitemap)
npm run build            # Production build (also runs gen:edit-routes, gen:last-updated, gen:sitemap)
npm run start            # Serve the production build (warns under `output: 'standalone'` — safe to ignore locally; prod runs `node server.js` from `.next/standalone`)
npm run lint             # ESLint (next/core-web-vitals) on src/
npm run lint:mdx         # Check MDX heading structure (scripts/lint-mdx-headings.mjs)
npm run gen              # Regenerate API docs from NetBird OpenAPI spec (requires a Go toolchain: runs `go run .` in generator/ to expand the spec)
npm run gen:edit-routes  # Regenerate edit-on-GitHub routes (auto-runs with dev/build)
npm run gen:last-updated # Regenerate per-page git last-modified dates (auto-runs with dev/build)
npm run gen:sitemap      # Regenerate public/sitemap.xml (auto-runs with dev/build)

Security boundaries

Public site, public repo. Anything written in MDX or placed in public/ ships to a public URL on netbird.io. Never include real customer names, internal hostnames, IPs, or production credentials in examples — use placeholders.
.env is committed and contains placeholders only (e.g. NEXT_PUBLIC_DOCSEARCH_API_KEY=APP_NEXT_PUBLIC_DOCSEARCH_API_KEY). These are build-time substitution targets. Real values belong in .env.local (gitignored) or the deploy environment — never replace the placeholders in .env with real secrets.
npm run gen pulls openapi.yml live from netbirdio/netbird@main with no pinning. Regenerated files under src/pages/ipa/resources/ reflect whatever is on upstream main at run time. Review the diff before committing.
This file is read as authoritative guidance by AI agents. Treat edits to CLAUDE.md with the same review rigor as CI config or a deploy script.

Architecture

Content Structure

Documentation pages are MDX files in src/pages/ using the Next.js Pages Router (not App Router). Key directories:

about-netbird/ - Conceptual docs
get-started/ - Installation and quickstart guides
manage/ - Feature documentation (peers, networks, DNS, access control, etc.)
selfhosted/ - Self-hosting deployment guides
ipa/ - API documentation (served at /api via rewrite)
use-cases/ - Tutorials and examples
client/ - Client configuration
agent-network/ - Agent Network product docs (AI/LLM gateway: quickstart, policies, usage & logs, integrations)
help/ - Troubleshooting

MDX Page Conventions

Page title comes from the first # Heading in the MDX file
Optional export const description = '...' for meta description
Import components as needed: import {Note} from "@/components/mdx"
Images go in public/docs-static/img/<section>/ and are referenced as /docs-static/img/<section>/filename.png

Two sidebar files, both must be kept in sync when adding or moving pages:

src/components/NavigationDocs.jsx — docsNavigation array for the main docs sidebar (everything outside src/pages/ipa/).
src/components/NavigationAPI.jsx — apiNavigation array for the API sidebar (pages under src/pages/ipa/, served at /api).

Both support nested links arrays for sub-navigation.

MDX Components

Custom components available in MDX files (see README.md for full usage examples):

Alert boxes: <Note>, <Warning>, <Success> (from @/components/mdx)
Layout: <Row>, <Col>, <Tiles> (from @/components/Tiles), <CodeGroup>
Media: <YouTube videoId="..."> (from @/components/YouTube)
UI: <Button> (from @/components/Button), <Badge>
API docs: <Properties>, <Property>
Diagrams: fenced ```mermaid code blocks render as Mermaid diagrams (via src/components/Mermaid.jsx)

API Documentation Generator

generator/ - TypeScript generator that creates MDX pages from the NetBird OpenAPI spec
generator/templates/ApiTemplate.ts - Template for generated pages
Output: src/pages/ipa/resources/ (don't edit these files manually)

MDX Processing Pipeline

mdx/remark.mjs - Remark plugins
mdx/rehype.mjs - Rehype plugins (syntax highlighting via Shiki)
mdx/recma.mjs - Recma plugins

Generated build data in `src/lib/`

Some files in src/lib/ look hand-written but are generated by gen:* scripts and gitignored:

src/lib/edit-on-github-routes.js — written by scripts/generate-github-routes.mjs
src/lib/last-updated-routes.mjs — written by scripts/generate-last-updated.mjs

They are imported at build time (e.g. by mdx/rehype.mjs). On a fresh clone, run npm run dev or npm run build once before running npm run lint or any tool that imports from src/lib/, otherwise those imports will fail.

URL Routing

Root / rewrites to /introduction
/api/* rewrites to /ipa/* (API docs live in src/pages/ipa/ but are served under /api)
src/proxy.js additionally rewrites /api data requests (x-nextjs-data header / /_next/data/... paths) to /ipa. The config rewrite loses data-request context on client-side navigation (Next.js issue #39669), which strips pageProps — don't remove or bypass the proxy when touching /api routing, and test client-side nav to /api pages after any change here.
Extensive legacy redirects from /docs/* and /how-to/* paths in next.config.mjs

6.1 KiB Raw Blame History