NetBird — Setup
Self-hosted WireGuard-based VPN mesh network. Runs as a multi-container Docker stack on LXC 115 (infra-pool). Provides secure remote access to the homelab via peer-to-peer connections with TURN/relay fallback. Uses PocketID for OIDC authentication.
Links
- Website: https://netbird.io
- Docs: https://docs.netbird.io
- GitHub: https://github.com/netbirdio/netbird
Infrastructure
| Host | Internal | URL |
|---|---|---|
| Docker (LXC 115) | 192.168.1.115 | https://vpn.eva-00.network (dashboard) |
Containers
| Container | Port | Purpose |
|---|---|---|
| netbird-management | 33073 | API + management server |
| netbird-dashboard | 80 | Web UI |
| netbird-signal | 10000 | Peer signaling (gRPC) |
| netbird-relay | — | Traffic relay |
| netbird-coturn | 3478 (UDP) | TURN/STUN server |
Network requirements
- UDP 3478 must be forwarded on the router to 192.168.1.115 (TURN/STUN)
Observability
Logs
NetBird logs are collected via Grafana Alloy Docker discovery and shipped to Loki.
| Query | Purpose |
|---|---|
{job="netbird", container="netbird-management"} |
Peer registration, auth, network config |
{job="netbird", container="netbird-dashboard"} |
Web UI events |
{job="netbird", container="netbird-signal"} |
Peer signaling events |
{job="netbird", container="netbird-relay"} |
Traffic relay events |
{job="netbird", container="netbird-coturn"} |
TURN/STUN connection events |
Access: Grafana → Explore → Loki → Enter query
Metrics
NetBird does not export Prometheus metrics in this deployment. Use Loki logs to diagnose issues.
IaC
| Artifact | Path |
|---|---|
| Playbook | ansible/playbooks/netbird.yml |
| Workflow | .forgejo/workflows/netbird.yml |
| Compose | services/netbird/docker-compose.yml |
| Management config | services/netbird/management.json.j2 (templated) |
| TURN config | services/netbird/turnserver.conf.j2 (templated) |
Secrets
secret/netbird → oidc_client_id, oidc_client_secret, turn_password, relay_secret
secret/pocketid → api_key (used for OIDC integration)
Authentication
NetBird uses PocketID as its OIDC identity provider. Peers authenticate via the NetBird client, which redirects to PocketID for login.
File paths on LXC 115
| Path | Contents |
|---|---|
/opt/netbird/docker-compose.yml |
Docker Compose stack |
/opt/netbird/management.json |
Management server config (templated from Vault secrets) |
/opt/netbird/turnserver.conf |
TURN/STUN server config (templated from Vault secrets) |
/opt/netbird/.env |
Environment variables (OIDC client ID, relay secret) |