mirror of
https://github.com/netbirdio/docs.git
synced 2026-08-24 16:51:26 +02:00
f403129f66
* 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
94 lines
6.1 KiB
Markdown
94 lines
6.1 KiB
Markdown
# 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](https://netbird.io), 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
|
|
|
|
```bash
|
|
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`
|
|
|
|
### Navigation
|
|
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`
|