sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-04-16 07:26:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Adjust docs according to new getting satrted

Browse Source
This commit is contained in:
braginini
2026-02-12 17:40:24 +01:00
parent f06ba8855f
commit a4f2765c73
10 changed files with 178 additions and 149 deletions
Download Patch File Download Diff File Expand all files Collapse all files

253
src/pages/selfhosted/configuration-files.mdx
View File

@@ -15,10 +15,9 @@ A standard NetBird self-hosted deployment uses the following configuration files
| File | Purpose | | File | Purpose |
|------|---------| |------|---------|
| `docker-compose.yml` | Defines all NetBird services (dashboard, netbird-server), their Docker images, port mappings, volumes, and startup order. Modify this to change resource limits, add services, or adjust networking. | | `docker-compose.yml` | Defines all NetBird services (dashboard, netbird-server, traefik), their Docker images, port mappings, volumes, and startup order. Modify this to change resource limits, add services, or adjust networking. |
| `config.yaml` | Central configuration for the NetBird server including listen addresses, authentication settings, STUN ports, and database configuration. Changes here affect how peers connect and authenticate. | | `config.yaml` | Central configuration for the NetBird server including listen addresses, authentication settings, STUN ports, and database configuration. Changes here affect how peers connect and authenticate. |
| `dashboard.env` | Configures the web dashboard including API endpoints, OAuth2/OIDC settings, and optional SSL settings for standalone deployments without a reverse proxy. | | `dashboard.env` | Configures the web dashboard including API endpoints, OAuth2/OIDC settings, and optional SSL settings for standalone deployments without a reverse proxy. |
| `Caddyfile` | Configures the built-in Caddy reverse proxy for SSL termination and routing requests to NetBird services. Only present when using the default `getting-started.sh` deployment with Caddy. |
### File Locations ### File Locations
@@ -28,8 +27,7 @@ After running the installation script, configuration files are located in the di
./ ./
├── docker-compose.yml ├── docker-compose.yml
├── config.yaml ├── config.yaml
├── dashboard.env └── dashboard.env
└── Caddyfile # Only when using built-in Caddy
``` ```
--- ---
@@ -44,138 +42,157 @@ The Docker Compose file defines all NetBird services, their dependencies, networ
|---------|-------|---------------|-------------------|-------------| |---------|-------|---------------|-------------------|-------------|
| `dashboard` | `netbirdio/dashboard` | 80 | 8080:80 | The web-based management console where administrators configure networks, manage peers, create access policies, and view activity logs. Includes an embedded nginx server for serving the UI. | | `dashboard` | `netbirdio/dashboard` | 80 | 8080:80 | The web-based management console where administrators configure networks, manage peers, create access policies, and view activity logs. Includes an embedded nginx server for serving the UI. |
| `netbird-server` | `netbirdio/netbird-server` | 80, 3478/udp | 8081:80, 3478:3478/udp | The combined NetBird server that includes management, signal, and relay services in a single container. Also provides embedded STUN on UDP 3478 for NAT type detection. | | `netbird-server` | `netbirdio/netbird-server` | 80, 3478/udp | 8081:80, 3478:3478/udp | The combined NetBird server that includes management, signal, and relay services in a single container. Also provides embedded STUN on UDP 3478 for NAT type detection. |
| `caddy` | `caddy` | 80, 443 | 80:80, 443:443 | Handles TLS termination and routes incoming HTTPS requests to the appropriate NetBird services. Only included in default `getting-started.sh` deployments; can be replaced with your own reverse proxy. | | `traefik` | `traefik:v3.6` | 80, 443 | 80:80, 443:443 | Handles TLS termination via Let's Encrypt and routes incoming HTTPS requests to the appropriate NetBird services. Only included in default `getting-started.sh` deployments; can be replaced with your own reverse proxy. |
<Note> <Note>
**Internal vs External ports**: Internal ports are what services listen on inside their containers. External (Exposed) ports show the host-to-container mapping used when running without the built-in Caddy (e.g., with Nginx, Traefik, or other reverse proxies). When using the default Caddy deployment, only Caddy exposes ports externally. **Internal vs External ports**: Internal ports are what services listen on inside their containers. External (Exposed) ports show the host-to-container mapping used when running without the built-in Traefik (e.g., with Nginx or other reverse proxies). When using the default Traefik deployment, only Traefik exposes ports externally.
</Note> </Note>
<Note> <Note>
The combined server includes an embedded STUN server, eliminating the need for a separate coturn container. STUN functionality is configured via the `stunPorts` setting in `config.yaml`. The combined server includes an embedded STUN server, eliminating the need for a separate coturn container. STUN functionality is configured via the `stunPorts` setting in `config.yaml`.
</Note> </Note>
### Default Settings ### Default Deployment (Built-in Traefik)
The compose file includes these defaults applied to all services: The default `getting-started.sh` deployment generates a Docker Compose file with three services: Traefik (reverse proxy with automatic TLS), the dashboard, and the combined NetBird server. Traefik uses Docker labels on each service to configure routing.
```yaml ```yaml
x-default: &default services:
restart: 'unless-stopped' # Traefik reverse proxy (automatic TLS via Let's Encrypt)
logging: traefik:
driver: 'json-file' image: traefik:v3.6
options: container_name: netbird-traefik
max-size: '500m' restart: unless-stopped
max-file: '2' networks: [netbird]
``` command:
- "--providers.docker=true"
- "--providers.docker.exposedbydefault=false"
- "--providers.docker.network=netbird"
- "--entrypoints.web.address=:80"
- "--entrypoints.websecure.address=:443"
- "--entrypoints.websecure.transport.respondingTimeouts.readTimeout=0"
- "--entrypoints.web.http.redirections.entrypoint.to=websecure"
- "--entrypoints.web.http.redirections.entrypoint.scheme=https"
- "--certificatesresolvers.letsencrypt.acme.tlschallenge=true"
- "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
ports:
- '443:443'
- '80:80'
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
- netbird_traefik_letsencrypt:/letsencrypt
### Dashboard Service # UI dashboard
dashboard:
image: netbirdio/dashboard:latest
container_name: netbird-dashboard
restart: unless-stopped
networks: [netbird]
env_file:
- ./dashboard.env
labels:
- traefik.enable=true
- traefik.http.routers.netbird-dashboard.rule=Host(`netbird.example.com`)
- traefik.http.routers.netbird-dashboard.entrypoints=websecure
- traefik.http.routers.netbird-dashboard.tls=true
- traefik.http.routers.netbird-dashboard.tls.certresolver=letsencrypt
- traefik.http.routers.netbird-dashboard.priority=1
- traefik.http.services.netbird-dashboard.loadbalancer.server.port=80
The dashboard provides the web interface for NetBird management. # Combined server (Management + Signal + Relay + STUN)
netbird-server:
image: netbirdio/netbird-server:latest
container_name: netbird-server
restart: unless-stopped
networks: [netbird]
ports:
- '3478:3478/udp'
volumes:
- netbird_data:/var/lib/netbird
- ./config.yaml:/etc/netbird/config.yaml
command: ["--config", "/etc/netbird/config.yaml"]
labels:
- traefik.enable=true
# gRPC router (needs h2c backend for HTTP/2 cleartext)
- traefik.http.routers.netbird-grpc.rule=Host(`netbird.example.com`) && (PathPrefix(`/signalexchange.SignalExchange/`) || PathPrefix(`/management.ManagementService/`))
- traefik.http.routers.netbird-grpc.entrypoints=websecure
- traefik.http.routers.netbird-grpc.tls=true
- traefik.http.routers.netbird-grpc.tls.certresolver=letsencrypt
- traefik.http.routers.netbird-grpc.service=netbird-server-h2c
# Backend router (relay, WebSocket, API, OAuth2)
- traefik.http.routers.netbird-backend.rule=Host(`netbird.example.com`) && (PathPrefix(`/relay`) || PathPrefix(`/ws-proxy/`) || PathPrefix(`/api`) || PathPrefix(`/oauth2`))
- traefik.http.routers.netbird-backend.entrypoints=websecure
- traefik.http.routers.netbird-backend.tls=true
- traefik.http.routers.netbird-backend.tls.certresolver=letsencrypt
- traefik.http.routers.netbird-backend.service=netbird-server
# Services
- traefik.http.services.netbird-server.loadbalancer.server.port=80
- traefik.http.services.netbird-server-h2c.loadbalancer.server.port=80
- traefik.http.services.netbird-server-h2c.loadbalancer.server.scheme=h2c
**With built-in Caddy (default):** volumes:
```yaml netbird_data:
dashboard: netbird_traefik_letsencrypt:
image: netbirdio/dashboard:latest
container_name: netbird-dashboard
restart: unless-stopped
networks: [netbird]
env_file:
- ./dashboard.env
logging:
driver: "json-file"
options:
max-size: "500m"
max-file: "2"
```
**With external reverse proxy (exposed ports):** networks:
```yaml netbird:
dashboard:
image: netbirdio/dashboard:latest
container_name: netbird-dashboard
restart: unless-stopped
networks: [netbird]
ports:
- '127.0.0.1:8080:80'
env_file:
- ./dashboard.env
logging:
driver: "json-file"
options:
max-size: "500m"
max-file: "2"
``` ```
<Note> <Note>
The dashboard service is configured via the `dashboard.env` file. See the [dashboard.env section](#dashboard-env) for the full list of environment variables. When using the built-in Caddy, no ports are exposed directly from the dashboard container; Caddy routes traffic to it internally. The `readTimeout=0` on the websecure entrypoint is required for gRPC long-lived streams (Management sync and Signal). Without it, Traefik's default 60-second timeout disconnects clients periodically.
</Note> </Note>
### Combined NetBird Server Service
The combined NetBird server is the core of NetBird, handling peer registration, authentication, signaling, and relay in a single container.
**With built-in Caddy (default):**
```yaml
netbird-server:
image: netbirdio/netbird-server:latest
container_name: netbird-server
restart: unless-stopped
networks: [netbird]
ports:
- '3478:3478/udp' # Embedded STUN server (must be exposed publicly)
volumes:
- netbird_data:/var/lib/netbird
- ./config.yaml:/etc/netbird/config.yaml
command: ["--config", "/etc/netbird/config.yaml"]
logging:
driver: "json-file"
options:
max-size: "500m"
max-file: "2"
```
**With external reverse proxy (exposed ports):**
```yaml
netbird-server:
image: netbirdio/netbird-server:latest
container_name: netbird-server
restart: unless-stopped
networks: [netbird]
ports:
- '127.0.0.1:8081:80' # HTTP (for reverse proxy)
- '3478:3478/udp' # Embedded STUN server (must be exposed publicly)
volumes:
- netbird_data:/var/lib/netbird
- ./config.yaml:/etc/netbird/config.yaml
command: ["--config", "/etc/netbird/config.yaml"]
logging:
driver: "json-file"
options:
max-size: "500m"
max-file: "2"
```
<Note> <Note>
The STUN port (3478/udp) must always be exposed publicly, regardless of reverse proxy configuration. STUN uses UDP for NAT detection and cannot be proxied through HTTP reverse proxies. The STUN port (3478/udp) must always be exposed publicly, regardless of reverse proxy configuration. STUN uses UDP for NAT detection and cannot be proxied through HTTP reverse proxies.
</Note> </Note>
To use an external database, add environment variables: ### With External Reverse Proxy (Exposed Ports)
When using your own reverse proxy (Nginx, external Traefik, etc.), the script generates a simpler compose file without the Traefik container, exposing service ports on localhost instead:
```yaml ```yaml
environment: services:
- NETBIRD_STORE_ENGINE_POSTGRES_DSN=postgres://user:password@host:5432/netbird dashboard:
# Or for MySQL: image: netbirdio/dashboard:latest
# - NETBIRD_STORE_ENGINE_MYSQL_DSN=user:password@tcp(host:3306)/netbird container_name: netbird-dashboard
restart: unless-stopped
networks: [netbird]
ports:
- '127.0.0.1:8080:80'
env_file:
- ./dashboard.env
netbird-server:
image: netbirdio/netbird-server:latest
container_name: netbird-server
restart: unless-stopped
networks: [netbird]
ports:
- '127.0.0.1:8081:80'
- '3478:3478/udp'
volumes:
- netbird_data:/var/lib/netbird
- ./config.yaml:/etc/netbird/config.yaml
command: ["--config", "/etc/netbird/config.yaml"]
volumes:
netbird_data:
networks:
netbird:
``` ```
Your reverse proxy should forward traffic to `127.0.0.1:8081` for the NetBird server and `127.0.0.1:8080` for the dashboard. gRPC routes require HTTP/2 (h2c) upstream support.
### Volume Configuration ### Volume Configuration
| Volume | Mount Point | Purpose | | Volume | Mount Point | Purpose |
|--------|-------------|---------| |--------|-------------|---------|
| `netbird_data` | `/var/lib/netbird` | Stores the management database (SQLite by default), encryption keys, and persistent state. Back up this volume regularly to preserve your accounts, peers, policies, and setup keys. | | `netbird_data` | `/var/lib/netbird` | Stores the management database (SQLite by default), encryption keys, and persistent state. Back up this volume regularly to preserve your accounts, peers, policies, and setup keys. |
| `netbird_caddy_data` | `/data` | Stores Caddy's TLS certificates and other persistent data. Only used when deploying with the built-in Caddy reverse proxy. Preserve this volume to maintain TLS certificates across restarts. | | `netbird_traefik_letsencrypt` | `/letsencrypt` | Stores Traefik's Let's Encrypt TLS certificates. Only used when deploying with the built-in Traefik reverse proxy. Preserve this volume to maintain TLS certificates across restarts. |
<Note> <Note>
The `getting-started.sh` deployment uses only two volumes: `netbird_data` for the server database and `netbird_caddy_data` for Caddy's certificate storage. The `getting-started.sh` deployment uses only two volumes: `netbird_data` for the server database and `netbird_traefik_letsencrypt` for Traefik's certificate storage.
</Note> </Note>
--- ---
@@ -201,11 +218,8 @@ server:
dataDir: "/var/lib/netbird" dataDir: "/var/lib/netbird"
auth: auth:
enabled: true
issuer: "https://netbird.example.com/oauth2" issuer: "https://netbird.example.com/oauth2"
signKeyRefreshEnabled: true signKeyRefreshEnabled: true
storage:
type: "sqlite3"
dashboardRedirectURIs: dashboardRedirectURIs:
- "https://netbird.example.com/nb-auth" - "https://netbird.example.com/nb-auth"
- "https://netbird.example.com/nb-silent-auth" - "https://netbird.example.com/nb-silent-auth"
@@ -213,7 +227,8 @@ server:
- "http://localhost:53000/" - "http://localhost:53000/"
store: store:
engine: "sqlite" engine: "sqlite" # sqlite, postgres, or mysql
dsn: "" # Connection string for postgres or mysql
encryptionKey: "your-encryption-key" encryptionKey: "your-encryption-key"
``` ```
@@ -254,18 +269,12 @@ server:
Configures the built-in identity provider that handles user authentication and management. Configures the built-in identity provider that handles user authentication and management.
<Properties> <Properties>
<Property name="auth.enabled" type="boolean">
Enable the embedded identity provider. When `true`, the server hosts OAuth2/OIDC endpoints at `/oauth2/`.
</Property>
<Property name="auth.issuer" type="string"> <Property name="auth.issuer" type="string">
The OAuth2/OIDC issuer URL (e.g., `https://netbird.example.com/oauth2`). This URL is used to validate JWT tokens. The OAuth2/OIDC issuer URL (e.g., `https://netbird.example.com/oauth2`). This URL is used to validate JWT tokens.
</Property> </Property>
<Property name="auth.signKeyRefreshEnabled" type="boolean"> <Property name="auth.signKeyRefreshEnabled" type="boolean">
Enables automatic refresh of IdP signing keys. Recommended for production. Enables automatic refresh of IdP signing keys. Recommended for production.
</Property> </Property>
<Property name="auth.storage.type" type="string">
Storage backend for IdP data. Default: `sqlite3`
</Property>
<Property name="auth.dashboardRedirectURIs" type="array"> <Property name="auth.dashboardRedirectURIs" type="array">
OAuth2 redirect URIs for the dashboard application. OAuth2 redirect URIs for the dashboard application.
</Property> </Property>
@@ -274,7 +283,7 @@ Configures the built-in identity provider that handles user authentication and m
</Property> </Property>
</Properties> </Properties>
When `auth.enabled` is `true`, the server automatically: The embedded identity provider is always enabled in the combined server. It automatically:
- Hosts OIDC discovery at `https://your-domain/oauth2/.well-known/openid-configuration` - Hosts OIDC discovery at `https://your-domain/oauth2/.well-known/openid-configuration`
- Provides JWKS (signing keys) at `https://your-domain/oauth2/keys` - Provides JWKS (signing keys) at `https://your-domain/oauth2/keys`
- Handles token issuance at `https://your-domain/oauth2/token` - Handles token issuance at `https://your-domain/oauth2/token`
@@ -289,6 +298,9 @@ Configures the database backend for storing all NetBird data.
<Property name="store.engine" type="string"> <Property name="store.engine" type="string">
Database engine. Options: `sqlite`, `postgres`, `mysql`. Default: `sqlite` Database engine. Options: `sqlite`, `postgres`, `mysql`. Default: `sqlite`
</Property> </Property>
<Property name="store.dsn" type="string">
Connection string for postgres or mysql engines. For postgres: `host=localhost user=netbird password=secret dbname=netbird port=5432`. Alternatively, use the `NETBIRD_STORE_ENGINE_POSTGRES_DSN` or `NETBIRD_STORE_ENGINE_MYSQL_DSN` environment variables.
</Property>
<Property name="store.encryptionKey" type="string"> <Property name="store.encryptionKey" type="string">
Key used to encrypt sensitive data in the database. Keep this secure and backed up. Key used to encrypt sensitive data in the database. Keep this secure and backed up.
</Property> </Property>
@@ -354,13 +366,13 @@ AUTH_SUPPORTED_SCOPES=openid profile email groups
AUTH_REDIRECT_URI=/nb-auth AUTH_REDIRECT_URI=/nb-auth
AUTH_SILENT_REDIRECT_URI=/nb-silent-auth AUTH_SILENT_REDIRECT_URI=/nb-silent-auth
# SSL - disabled when behind reverse proxy (Caddy handles TLS) # SSL - disabled when behind reverse proxy (Traefik handles TLS)
NGINX_SSL_PORT=443 NGINX_SSL_PORT=443
LETSENCRYPT_DOMAIN=none LETSENCRYPT_DOMAIN=none
``` ```
<Note> <Note>
When using the built-in Caddy or an external reverse proxy, set `LETSENCRYPT_DOMAIN=none` because the reverse proxy handles TLS termination. Only set a domain here if running the dashboard standalone without a reverse proxy. When using the built-in Traefik or an external reverse proxy, set `LETSENCRYPT_DOMAIN=none` because the reverse proxy handles TLS termination. Only set a domain here if running the dashboard standalone without a reverse proxy.
</Note> </Note>
### Endpoint Configuration ### Endpoint Configuration
@@ -398,7 +410,7 @@ The dashboard container's embedded nginx server can be configured using these en
The `NGINX_SSL_PORT` and Let's Encrypt variables are **only necessary when running the dashboard standalone** without an external reverse proxy. In standalone mode, the dashboard's embedded nginx handles SSL/TLS termination directly. The `NGINX_SSL_PORT` and Let's Encrypt variables are **only necessary when running the dashboard standalone** without an external reverse proxy. In standalone mode, the dashboard's embedded nginx handles SSL/TLS termination directly.
**For most installations** that use the built-in Caddy reverse proxy (the default `getting-started.sh` deployment) or an external reverse proxy like Traefik or Nginx, **you do not need to configure these nginx variables**. The reverse proxy handles SSL termination and routes traffic to the dashboard container, which serves content over HTTP internally. **For most installations** that use the built-in Traefik reverse proxy (the default `getting-started.sh` deployment) or an external reverse proxy like Nginx, **you do not need to configure these nginx variables**. The reverse proxy handles SSL termination and routes traffic to the dashboard container, which serves content over HTTP internally.
When behind a reverse proxy: When behind a reverse proxy:
- Set `LETSENCRYPT_DOMAIN=none` to disable the dashboard's internal Let's Encrypt - Set `LETSENCRYPT_DOMAIN=none` to disable the dashboard's internal Let's Encrypt
@@ -414,18 +426,19 @@ When behind a reverse proxy:
To use PostgreSQL instead of SQLite: To use PostgreSQL instead of SQLite:
1. Update `config.yaml`: Update `config.yaml`:
```yaml ```yaml
server: server:
store: store:
engine: "postgres" engine: "postgres"
dsn: "host=db-server user=netbird password=secret dbname=netbird port=5432"
``` ```
2. Set the connection string in `docker-compose.yml`: Alternatively, you can use an environment variable instead of putting the DSN in the config file:
```yaml ```yaml
netbird-server: netbird-server:
environment: environment:
- NETBIRD_STORE_ENGINE_POSTGRES_DSN=postgres://user:password@host:5432/netbird?sslmode=disable - NETBIRD_STORE_ENGINE_POSTGRES_DSN=host=db-server user=netbird password=secret dbname=netbird port=5432
``` ```
See [Management Postgres Store](/selfhosted/postgres-store) for detailed setup. See [Management Postgres Store](/selfhosted/postgres-store) for detailed setup.
@@ -454,7 +467,7 @@ netbird-server:
When running behind your own reverse proxy (Traefik, Nginx, etc.): When running behind your own reverse proxy (Traefik, Nginx, etc.):
1. Set `LETSENCRYPT_DOMAIN=none` in `dashboard.env` 1. Set `LETSENCRYPT_DOMAIN=none` in `dashboard.env`
2. The combined server handles trusted proxy detection automatically when running behind Caddy or other proxies. 2. The combined server handles trusted proxy detection automatically when running behind Traefik or other proxies.
See [Reverse Proxy Configuration](/selfhosted/reverse-proxy) for detailed templates. See [Reverse Proxy Configuration](/selfhosted/reverse-proxy) for detailed templates.

10
src/pages/selfhosted/maintenance/backup.mdx
View File

@@ -5,17 +5,17 @@ To back up your NetBird installation, you need to copy the configuration files a
The configuration files are located in the folder where you ran [the installation script](/selfhosted/selfhosted-quickstart#installation-script). To back up, copy the files to a backup location: The configuration files are located in the folder where you ran [the installation script](/selfhosted/selfhosted-quickstart#installation-script). To back up, copy the files to a backup location:
```bash ```bash
mkdir backup mkdir backup
cp docker-compose.yml Caddyfile dashboard.env management.json relay.env backup/ cp docker-compose.yml dashboard.env config.yaml backup/
``` ```
<Note> <Note>
For detailed information about each configuration file and its options, see the [Configuration Files Reference](/selfhosted/configuration-files). For detailed information about each configuration file and its options, see the [Configuration Files Reference](/selfhosted/configuration-files).
</Note> </Note>
To save the Management service databases, stop the Management service and copy the files from the store directory: To save the server databases, stop the server and copy the files from the data directory:
```bash ```bash
docker compose stop management docker compose stop netbird-server
docker compose cp -a management:/var/lib/netbird/ backup/ docker compose cp -a netbird-server:/var/lib/netbird/ backup/
docker compose start management docker compose start netbird-server
``` ```
## Get In Touch ## Get In Touch

2
src/pages/selfhosted/maintenance/remove.mdx
View File

@@ -5,7 +5,7 @@ To remove the NetBird installation and all related data from your server, run th
# remove all NetBird-related containers and volumes (data) # remove all NetBird-related containers and volumes (data)
docker compose down --volumes docker compose down --volumes
# remove downloaded and generated config files # remove downloaded and generated config files
rm -f docker-compose.yml Caddyfile dashboard.env management.json relay.env rm -f docker-compose.yml dashboard.env config.yaml nginx-netbird.conf caddyfile-netbird.txt npm-advanced-config.txt
``` ```
## Get In Touch ## Get In Touch

5
src/pages/selfhosted/maintenance/scaling/migrate-sqlite-to-postgresql.mdx
View File

@@ -95,14 +95,15 @@ server:
store: store:
engine: "postgres" engine: "postgres"
dsn: "host=postgres-server user=postgres password=password dbname=postgres port=5432"
``` ```
Then pass the PostgreSQL connection string as an environment variable in your `docker-compose.yml`: Alternatively, you can pass the connection string as an environment variable instead of putting it in the config file:
```yaml ```yaml
netbird-server: netbird-server:
environment: environment:
- NETBIRD_STORE_ENGINE_POSTGRES_DSN=postgres://postgres:password@postgres-server:5432/postgres - NETBIRD_STORE_ENGINE_POSTGRES_DSN=host=postgres-server user=postgres password=password dbname=postgres port=5432
``` ```
## Restart and Verify ## Restart and Verify

6
src/pages/selfhosted/maintenance/scaling/scaling-your-self-hosted-deployment.mdx
View File

@@ -19,10 +19,10 @@ This guide assumes you have already [deployed a single-server NetBird](/selfhost
## Architecture Overview ## Architecture Overview
The default single-server deployment runs all services on one machine: **Caddy** (reverse proxy), **Dashboard** (web UI), The default single-server deployment runs all services on one machine: **Traefik** (reverse proxy), **Dashboard** (web UI),
and a **combined netbird-server** container that includes Management, Signal, and Relay + STUN as components. Caddy handles TLS termination on ports 80/443, while STUN listens on UDP port 3478. The Management server uses a **SQLite** database by default. and a **combined netbird-server** container that includes Management, Signal, and Relay + STUN as components. Traefik handles TLS termination on ports 80/443, while STUN listens on UDP port 3478. The Management server uses a **SQLite** database by default.
After splitting, the **main server** keeps Caddy, Dashboard, Management, and optionally Signal. After splitting, the **main server** keeps Traefik, Dashboard, Management, and optionally Signal.
The **relay servers** run independently on different machines, each handling relay (port 443) and STUN (port 3478) traffic. Peers receive relay addresses from the Management server and connect to them directly. Optionally, the SQLite database can be migrated to **PostgreSQL** on a dedicated server, and Signal can also be extracted to its own machine. The **relay servers** run independently on different machines, each handling relay (port 443) and STUN (port 3478) traffic. Peers receive relay addresses from the Management server and connect to them directly. Optionally, the SQLite database can be migrated to **PostgreSQL** on a dedicated server, and Signal can also be extracted to its own machine.
## Guides ## Guides

1
src/pages/selfhosted/maintenance/scaling/set-up-external-relays.mdx
View File

@@ -183,7 +183,6 @@ server:
credentialsTTL: "24h" credentialsTTL: "24h"
auth: auth:
enabled: true
issuer: "https://netbird.example.com/oauth2" issuer: "https://netbird.example.com/oauth2"
# ... rest of auth config # ... rest of auth config
``` ```

4
src/pages/selfhosted/maintenance/upgrade.mdx
View File

@@ -46,11 +46,11 @@ To upgrade NetBird to the latest version:
2. Review the release notes (see above) for any breaking changes. 2. Review the release notes (see above) for any breaking changes.
3. Pull the latest NetBird docker images: 3. Pull the latest NetBird docker images:
```bash ```bash
docker compose pull management dashboard signal relay docker compose pull netbird-server dashboard
``` ```
4. Restart the NetBird containers with the new images: 4. Restart the NetBird containers with the new images:
```bash ```bash
docker compose up -d --force-recreate management dashboard signal relay docker compose up -d --force-recreate netbird-server dashboard
``` ```
<Note> <Note>

6
src/pages/selfhosted/reverse-proxy.mdx
View File

@@ -1,6 +1,6 @@
# Reverse Proxy Configuration # Reverse Proxy Configuration
NetBird includes a built-in Caddy reverse proxy that handles TLS certificates automatically. However, if you already have an existing reverse proxy (Traefik, Nginx, etc.), you can configure NetBird to work with it instead. NetBird includes a built-in Traefik reverse proxy that handles TLS certificates automatically via Let's Encrypt. However, if you already have an existing reverse proxy (Nginx, Caddy, etc.), you can configure NetBird to work with it instead.
<Note> <Note>
Not all reverse proxies are supported as NetBird uses *gRPC* for various components. Your reverse proxy must support HTTP/2 and gRPC proxying. Not all reverse proxies are supported as NetBird uses *gRPC* for various components. Your reverse proxy must support HTTP/2 and gRPC proxying.
@@ -14,8 +14,8 @@ The `getting-started.sh` script supports multiple reverse proxy configurations.
``` ```
Which reverse proxy will you use? Which reverse proxy will you use?
[0] Built-in Caddy (recommended - automatic TLS) [0] Traefik (recommended - automatic TLS, included in Docker Compose)
[1] Traefik (labels added to containers) [1] Existing Traefik (labels for external Traefik instance)
[2] Nginx (generates config template) [2] Nginx (generates config template)
[3] Nginx Proxy Manager (generates config + instructions) [3] Nginx Proxy Manager (generates config + instructions)
[4] External Caddy (generates Caddyfile snippet) [4] External Caddy (generates Caddyfile snippet)

2
src/pages/selfhosted/selfhosted-guide.mdx
View File

@@ -201,7 +201,7 @@ docker compose logs dashboard
## Advanced: Running NetBird behind an existing reverse-proxy ## Advanced: Running NetBird behind an existing reverse-proxy
If you already have a reverse proxy (Traefik, Nginx, Caddy, etc.), you can configure NetBird to work with it instead of using the built-in Caddy. If you already have a reverse proxy (Nginx, Caddy, etc.), you can configure NetBird to work with it instead of using the built-in Traefik.
<Note> <Note>
Not all reverse proxies are supported as NetBird uses *gRPC* for various components. Your reverse proxy must support HTTP/2 and gRPC proxying. Not all reverse proxies are supported as NetBird uses *gRPC* for various components. Your reverse proxy must support HTTP/2 and gRPC proxying.

38
src/pages/selfhosted/selfhosted-quickstart.mdx
View File

@@ -39,8 +39,8 @@ The script will prompt you to select a reverse proxy option:
``` ```
Which reverse proxy will you use? Which reverse proxy will you use?
[0] Built-in Caddy (recommended - automatic TLS) [0] Traefik (recommended - automatic TLS, included in Docker Compose)
[1] Traefik (labels added to containers) [1] Existing Traefik (labels for external Traefik instance)
[2] Nginx (generates config template) [2] Nginx (generates config template)
[3] Nginx Proxy Manager (generates config + instructions) [3] Nginx Proxy Manager (generates config + instructions)
[4] External Caddy (generates Caddyfile snippet) [4] External Caddy (generates Caddyfile snippet)
@@ -49,7 +49,7 @@ Which reverse proxy will you use?
Enter choice [0-5] (default: 0): Enter choice [0-5] (default: 0):
``` ```
**For this quickstart guide, select option `[0]` (Built-in Caddy)** - just press Enter to use the default. This option handles TLS certificates automatically via Let's Encrypt and requires no additional configuration. **For this quickstart guide, select option `[0]` (Traefik)** - just press Enter to use the default. This option includes a Traefik container in the Docker Compose setup and handles TLS certificates automatically via Let's Encrypt with no additional configuration.
<Note> <Note>
If you already have a reverse proxy (Traefik, Nginx, etc.) and want to use it instead, the script will guide you through the setup. See the [Reverse Proxy Configuration](/selfhosted/reverse-proxy) guide for detailed instructions on each option. If you already have a reverse proxy (Traefik, Nginx, etc.) and want to use it instead, the script will guide you through the setup. See the [Reverse Proxy Configuration](/selfhosted/reverse-proxy) guide for detailed instructions on each option.
@@ -61,8 +61,8 @@ If you already have a reverse proxy (Traefik, Nginx, etc.) and want to use it in
root@selfhosted-1:~/netbird# bash getting-started.sh root@selfhosted-1:~/netbird# bash getting-started.sh
Which reverse proxy will you use? Which reverse proxy will you use?
[0] Built-in Caddy (recommended - automatic TLS) [0] Traefik (recommended - automatic TLS, included in Docker Compose)
[1] Traefik (labels added to containers) [1] Existing Traefik (labels for external Traefik instance)
[2] Nginx (generates config template) [2] Nginx (generates config template)
[3] Nginx Proxy Manager (generates config + instructions) [3] Nginx Proxy Manager (generates config + instructions)
[4] External Caddy (generates Caddyfile snippet) [4] External Caddy (generates Caddyfile snippet)
@@ -74,12 +74,12 @@ Rendering initial files...
Starting NetBird services Starting NetBird services
[+] up 6/6 [+] up 6/6
✔ Network combined_netbird Created 0.1s ✔ Network combined_netbird Created 0.1s
✔ Volume combined_netbird_data Created 0.0s ✔ Volume combined_netbird_data Created 0.0s
✔ Volume combined_netbird_caddy_data Created 0.0s ✔ Volume combined_netbird_traefik_letsencrypt Created 0.0s
✔ Container netbird-server Created 0.1s ✔ Container netbird-server Created 0.1s
✔ Container netbird-caddy Created 0.1s ✔ Container netbird-traefik Created 0.1s
✔ Container netbird-dashboard Created 0.1s ✔ Container netbird-dashboard Created 0.1s
Waiting for NetBird server to become ready . . . done Waiting for NetBird server to become ready . . . done
Done! Done!
@@ -148,6 +148,22 @@ Once your NetBird instance is running, refer to these guides for ongoing mainten
]} ]}
/> />
<Tiles
id="scaling"
items={[
{
href: '/selfhosted/maintenance/scaling/scaling-your-self-hosted-deployment',
name: 'Scaling Your Self-Hosted Deployment',
description: 'Split your NetBird deployment into multiple nodes to scale your deployment.',
},
{
href: '/selfhosted/configuration-files',
name: 'Configuration Files Reference',
description: 'Learn more about the configuration files generated by the quick start script and how to customize them.',
},
]}
/>
--- ---
## Troubleshoot ## Troubleshoot