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

Add environment variables documentation for self-hosted deployments (#553)

Browse Source 
Adds a comprehensive reference page for all environment variables used
when self-hosting NetBird, covering Management Server, Signal Server,
Relay Server, Dashboard, and Coturn services. Focuses on the new
embedded identity provider approach, removing deprecated external IDP
configuration variables.
This commit is contained in:
shuuri-labs
2026-01-19 18:20:52 +01:00
committed by GitHub
parent c6f347fea2
commit 8b04229096
2 changed files with 273 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
src/components/NavigationDocs.jsx
View File

@@ -321,6 +321,7 @@ export const docsNavigation = [
},
{ title: 'Reverse Proxy', href: '/selfhosted/reverse-proxy' },
{ title: 'Advanced Guide', href: '/selfhosted/selfhosted-guide' },
{ title: 'Environment Variables', href: '/selfhosted/environment-variables' },
{ title: 'Management SQLite Store', href: '/selfhosted/sqlite-store' },
{ title: 'Management Postgres Store', href: '/selfhosted/postgres-store' },
{ title: 'Activity Events Postgres Store', href: '/selfhosted/activity-postgres-store' },

272
src/pages/selfhosted/environment-variables.mdx Normal file
View File

@@ -0,0 +1,272 @@
import {Note} from "@/components/mdx";
# Environment Variables Configuration
This page provides a comprehensive reference for all environment variables available when self-hosting NetBird. Environment variables allow you to configure the Management Server, Signal Server, Relay Server, Dashboard, and Coturn (TURN) services.
<Note>
Environment variables set in your `setup.env` file are used by the `configure.sh` script to generate the final configuration files. Changes to `setup.env` require re-running `./configure.sh` to take effect.
</Note>
## Overview
NetBird uses two types of environment variables:
1. **Setup Variables** (`NETBIRD_` prefix) - Used in docker-compose templates and `setup.env` for initial configuration
2. **Runtime Variables** (`NB_` prefix) - Can override CLI flags at runtime using the pattern `--flag-name` → `NB_FLAG_NAME`
## Core Setup Variables
These variables are set in your `setup.env` file before running the configuration script.
### Domain and Network
| Variable | Description | Example |
|----------|-------------|---------|
| `NETBIRD_DOMAIN` | Your NetBird domain name | `netbird.example.com` |
| `NETBIRD_LETSENCRYPT_EMAIL` | Email for Let's Encrypt certificates | `admin@example.com` |
| `NETBIRD_DISABLE_LETSENCRYPT` | Disable automatic Let's Encrypt | `true` |
### Port Configuration
| Variable | Default | Description |
|----------|---------|-------------|
| `NETBIRD_MGMT_API_PORT` | `33073` | Management API port |
| `NETBIRD_SIGNAL_PORT` | `10000` | Signal server port |
| `NETBIRD_RELAY_PORT` | `33080` | Relay server port |
| `NGINX_SSL_PORT` | `443` | Dashboard HTTPS port |
### TURN Server
| Variable | Default | Description |
|----------|---------|-------------|
| `TURN_DOMAIN` | Same as `NETBIRD_DOMAIN` | TURN server domain |
| `TURN_USER` | Auto-generated | TURN authentication username |
| `TURN_PASSWORD` | Auto-generated | TURN authentication password |
| `TURN_MIN_PORT` | `49152` | Minimum TURN relay port |
| `TURN_MAX_PORT` | `65535` | Maximum TURN relay port |
## Management Server Variables
### Database Configuration
| Variable | Default | Description |
|----------|---------|-------------|
| `NETBIRD_STORE_CONFIG_ENGINE` | `sqlite` | Store engine: `sqlite`, `postgres`, or `mysql` |
| `NETBIRD_STORE_ENGINE_POSTGRES_DSN` | - | PostgreSQL connection string |
| `NETBIRD_STORE_ENGINE_MYSQL_DSN` | - | MySQL connection string |
| `NETBIRD_DATASTORE_ENC_KEY` | Auto-generated | Encryption key for sensitive data |
<Note>
See [Management Postgres Store](/selfhosted/postgres-store) for PostgreSQL setup details.
</Note>
### Single Account Mode
| Variable | Default | Description |
|----------|---------|-------------|
| `NETBIRD_MGMT_SINGLE_ACCOUNT_MODE_DOMAIN` | - | Domain for single account mode |
<Note>
NetBird runs in single account mode by default since v0.10.1. All users joining your self-hosted instance will be part of the same account/network.
</Note>
### Relay Configuration
| Variable | Description |
|----------|-------------|
| `NETBIRD_RELAY_ENDPOINT` | Relay server endpoint URL |
| `NETBIRD_RELAY_AUTH_SECRET` | Shared authentication secret for relay |
### Signal Configuration
| Variable | Description |
|----------|-------------|
| `NETBIRD_SIGNAL_PROTOCOL` | Protocol: `http` or `https` |
### DNS Configuration
| Variable | Default | Description |
|----------|---------|-------------|
| `NETBIRD_MGMT_DNS_DOMAIN` | `netbird.selfhosted` | DNS domain for peer resolution |
### TLS/Certificates
| Variable | Description |
|----------|-------------|
| `NETBIRD_MGMT_API_CERT_FILE` | Path to TLS certificate file |
| `NETBIRD_MGMT_API_CERT_KEY_FILE` | Path to TLS certificate key file |
### Metrics and Analytics
| Variable | Default | Description |
|----------|---------|-------------|
| `NETBIRD_DISABLE_ANONYMOUS_METRICS` | `false` | Disable anonymous usage metrics |
## Runtime Environment Variables (NB_ prefix)
These variables can override CLI flags at runtime. The naming convention is `NB_<FLAG_NAME>` where the flag name is uppercased and hyphens are replaced with underscores.
### Management Server Runtime
| Variable | Description |
|----------|-------------|
| `NB_PORT` | Server port (overrides `--port`) |
| `NB_DATADIR` | Data directory (overrides `--datadir`) |
| `NB_CONFIG` | Config file path (overrides `--config`) |
| `NB_LOG_LEVEL` | Log level: `debug`, `info`, `warn`, `error` |
| `NB_LOG_FILE` | Log file path |
| `NB_METRICS_PORT` | Prometheus metrics port |
| `NB_LETSENCRYPT_DOMAIN` | Let's Encrypt domain |
| `NB_CERT_FILE` | TLS certificate file |
| `NB_CERT_KEY` | TLS certificate key file |
| `NB_DNS_DOMAIN` | DNS domain for peers |
| `NB_DISABLE_GEOLITE_UPDATE` | Disable GeoLite database updates |
### Advanced Runtime Variables
| Variable | Description |
|----------|-------------|
| `NB_EVENT_ACTIVITY_LOG_ENABLED` | Enable activity log events |
| `NB_GET_ACCOUNT_BUFFER_INTERVAL` | Account buffer interval duration |
| `NB_SQL_MAX_OPEN_CONNS` | Maximum SQL database connections |
| `NB_STORE_TRANSACTION_TIMEOUT` | Store transaction timeout |
| `NB_API_RATE_LIMITING_ENABLED` | Enable API rate limiting |
| `NB_API_RATE_LIMITING_RPM` | Rate limit requests per minute |
| `NB_API_RATE_LIMITING_BURST` | Rate limit burst size |
| `NETBIRD_METRICS_INTERVAL_IN_SECONDS` | Metrics push interval |
## Signal Server Variables
### Runtime Variables
| Variable | Description |
|----------|-------------|
| `NB_PORT` | Signal server port |
| `NB_METRICS_PORT` | Prometheus metrics port |
| `NB_SSL_DIR` | SSL certificates directory |
| `NB_LETSENCRYPT_DOMAIN` | Let's Encrypt domain |
| `NB_CERT_FILE` | TLS certificate file |
| `NB_CERT_KEY` | TLS certificate key file |
| `NB_LOG_LEVEL` | Log level |
| `NB_LOG_FILE` | Log file path |
## Relay Server Variables
### Setup Variables
| Variable | Description |
|----------|-------------|
| `NETBIRD_RELAY_TAG` | Docker image tag |
| `NETBIRD_RELAY_PORT` | Relay port (default: 33080) |
| `NETBIRD_RELAY_ENDPOINT` | Relay endpoint address |
| `NETBIRD_RELAY_AUTH_SECRET` | Authentication secret |
| `NETBIRD_RELAY_DOMAIN` | Relay server domain |
### Runtime Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `NB_LOG_LEVEL` | `info` | Log level |
| `NB_LISTEN_ADDRESS` | `:443` | Listen address |
| `NB_EXPOSED_ADDRESS` | - | Exposed address for peers |
| `NB_AUTH_SECRET` | - | Authentication secret |
| `NB_METRICS_PORT` | - | Prometheus metrics port |
| `NB_TLS_CERT_FILE` | - | TLS certificate file |
| `NB_TLS_KEY_FILE` | - | TLS key file |
| `NB_LETSENCRYPT_DATA_DIR` | - | Let's Encrypt data directory |
| `NB_LETSENCRYPT_DOMAINS` | - | Let's Encrypt domains |
| `NB_LETSENCRYPT_EMAIL` | - | Let's Encrypt email |
| `NB_HEALTH_LISTEN_ADDRESS` | - | Health check listen address |
## Dashboard Variables
| Variable | Description |
|----------|-------------|
| `NETBIRD_MGMT_API_ENDPOINT` | Management API endpoint URL |
| `NETBIRD_MGMT_GRPC_API_ENDPOINT` | Management gRPC endpoint |
| `LETSENCRYPT_DOMAIN` | Let's Encrypt domain (set to `none` if using own certs) |
| `LETSENCRYPT_EMAIL` | Let's Encrypt email |
<Note>
Dashboard authentication is automatically configured when using the embedded identity provider. The dashboard connects to the management server's built-in OAuth2 endpoints.
</Note>
## Coturn (TURN Server) Variables
Coturn configuration is generated from templates using these variables:
| Variable | Default | Description |
|----------|---------|-------------|
| `TURN_DOMAIN` | - | TURN server domain |
| `TURN_USER` | - | TURN username |
| `TURN_PASSWORD` | - | TURN password |
| `TURN_MIN_PORT` | `49152` | Minimum relay port |
| `TURN_MAX_PORT` | `65535` | Maximum relay port |
| `TURN_EXTERNAL_IP_CONFIG` | - | External IP configuration |
<Note>
The Coturn service uses static ports: `3478` (STUN/TURN) and `5349` (TLS TURN).
</Note>
## Configuration Examples
### Basic Setup
```bash
# setup.env
NETBIRD_DOMAIN="netbird.example.com"
NETBIRD_LETSENCRYPT_EMAIL="admin@example.com"
```
### PostgreSQL Database
```bash
# setup.env
NETBIRD_STORE_CONFIG_ENGINE="postgres"
NETBIRD_STORE_ENGINE_POSTGRES_DSN="postgres://user:password@localhost:5432/netbird?sslmode=disable"
```
### Custom Ports (Behind Reverse Proxy)
```bash
# setup.env
NETBIRD_DOMAIN="netbird.example.com"
NETBIRD_DISABLE_LETSENCRYPT="true"
NETBIRD_MGMT_API_PORT="443"
NETBIRD_SIGNAL_PORT="443"
```
### Disable Anonymous Metrics
```bash
# setup.env
NETBIRD_DISABLE_ANONYMOUS_METRICS="true"
```
### Enable API Rate Limiting
Set these in your container environment or docker-compose:
```yaml
environment:
- NB_API_RATE_LIMITING_ENABLED=true
- NB_API_RATE_LIMITING_RPM=60
- NB_API_RATE_LIMITING_BURST=10
```
## Variable Precedence
Configuration values are applied in the following order (later values override earlier):
1. Default values
2. Configuration file (`management.json`)
3. Environment variables
4. Command-line flags
## See Also
- [Self-hosting Quickstart Guide](/selfhosted/selfhosted-quickstart)
- [Advanced Self-hosting Guide](/selfhosted/selfhosted-guide)
- [Management SQLite Store](/selfhosted/sqlite-store)
- [Management Postgres Store](/selfhosted/postgres-store)