65 lines
2.4 KiB
Markdown
65 lines
2.4 KiB
Markdown
# NetBird
|
|
|
|
Self-hosted NetBird with the combined management, signal, relay, and STUN server.
|
|
|
|
Kubernetes runs the server and dashboard in `netbird`. The server uses SQLite
|
|
in `netbird-pvc`; `k8s/config.yaml` contains the template and runtime renderer.
|
|
Prepare `netbird-secrets` from `k8s/secrets.yaml.example` before the first start.
|
|
|
|
## Routing and keys
|
|
|
|
The public hostname is set in the ConfigMap and ingress rules. Keep the issuer,
|
|
dashboard endpoints, and public routes consistent. HTTP, WebSocket, and gRPC
|
|
traffic go through Traefik; the STUN route uses UDP 3478. A CDN's HTTP proxy does
|
|
not provide that UDP listener.
|
|
|
|
`NETBIRD_PROXY_SUBNET` controls which forwarded client addresses are trusted.
|
|
Use the actual proxy network CIDR rather than assuming another lab's subnet.
|
|
Keep the datastore encryption key with every datastore backup. Regenerating it
|
|
can make stored credentials unreadable.
|
|
|
|
## Compose alternative
|
|
|
|
`compose.yaml` expects `entrypoint.sh`, a local `.env`, and two local files:
|
|
`secrets/relay-auth-secret` and `secrets/datastore-encryption-key`.
|
|
The reviewed main commit is missing the renderer and setup script.
|
|
`fix/netbird-compose-runtime` restores them. Merge that fix before following
|
|
these setup commands:
|
|
|
|
```sh
|
|
cd netbird
|
|
./setup.sh
|
|
$EDITOR .env
|
|
docker compose config --quiet
|
|
docker compose up -d
|
|
```
|
|
|
|
The setup script detects the IPv4 subnet of the external `proxy` network and
|
|
preserves existing secrets. Complete the initial owner setup through the public
|
|
TLS endpoint after starting the server.
|
|
|
|
## Optional host client
|
|
|
|
`client.compose.yaml` runs a host-network peer in a separate Compose project.
|
|
Set `NB_SETUP_KEY` and `NETBIRD_CLIENT_HOSTNAME` in the local `.env`, then run
|
|
`docker compose -f client.compose.yaml up -d`. It needs `/dev/net/tun` and elevated
|
|
network capabilities. The normal server deployment does not start this client.
|
|
|
|
## Backup
|
|
|
|
Back up the SQLite data while the server is stopped, together with the encryption
|
|
key, relay secret, and local configuration. Test a restore on an isolated host.
|
|
For Compose, the datastore volume has the explicit name `netbird_data`.
|
|
Do not use `docker compose down -v` when keeping the installation.
|
|
|
|
## Inspect
|
|
|
|
From the repository root:
|
|
|
|
```sh
|
|
kubectl get pods,svc,pvc -n netbird
|
|
kubectl get events -n netbird --sort-by=.metadata.creationTimestamp
|
|
```
|
|
|
|
See the [repository README](../README.md) for deployment selection.
|