diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index f9f46b59..108c4dc7 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -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' }, diff --git a/src/pages/selfhosted/environment-variables.mdx b/src/pages/selfhosted/environment-variables.mdx new file mode 100644 index 00000000..8dedcc12 --- /dev/null +++ b/src/pages/selfhosted/environment-variables.mdx @@ -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. + + +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. + + +## 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 | + + +See [Management Postgres Store](/selfhosted/postgres-store) for PostgreSQL setup details. + + +### Single Account Mode + +| Variable | Default | Description | +|----------|---------|-------------| +| `NETBIRD_MGMT_SINGLE_ACCOUNT_MODE_DOMAIN` | - | Domain for single account mode | + + +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. + + +### 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_` 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 | + + +Dashboard authentication is automatically configured when using the embedded identity provider. The dashboard connects to the management server's built-in OAuth2 endpoints. + + +## 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 | + + +The Coturn service uses static ports: `3478` (STUN/TURN) and `5349` (TLS TURN). + + +## 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)