netbird-docs/src/pages/selfhosted/environment-variables.mdx

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 (including the embedded STUN server), and Dashboard 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 |

### STUN Configuration

<Note>
The default quickstart deployment uses the relay service's embedded STUN server. The variables below configure STUN functionality within the relay container via `relay.env`.
</Note>

| Variable | Default | Description |
|----------|---------|-------------|
| `NB_ENABLE_STUN` | `true` | Enable embedded STUN server in relay |
| `NB_STUN_PORTS` | `3478` | STUN server UDP ports |
| `NB_STUN_LOG_LEVEL` | `info` | STUN server log level |

## 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 |
| `NB_SETUP_PAT_ENABLED` | Enable optional Personal Access Token creation from `/api/setup` during initial setup. See [Automated Setup](/selfhosted/automated-setup). |

### 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 |
| `NB_ENABLE_STUN` | `false` | Enable embedded STUN server |
| `NB_STUN_PORTS` | `3478` | STUN server UDP ports (comma-separated) |
| `NB_STUN_LOG_LEVEL` | `info` | STUN server log level |

## 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 (Legacy)

<Note>
The default quickstart deployment no longer uses a separate Coturn container. STUN functionality is now embedded in the relay service. The variables below are only relevant for legacy deployments or advanced configurations that still use Coturn.
</Note>

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 (`config.yaml` for combined setup, `management.json` for older multi-container setup)
3. Environment variables
4. Command-line flags

## See Also

- [Self-hosting Quickstart Guide](/selfhosted/selfhosted-quickstart)
- [Advanced Self-hosting Guide](/selfhosted/selfhosted-guide)
- [Configuration Files Reference](/selfhosted/configuration-files) - Detailed documentation for docker-compose.yml, config.yaml, and other config files
- [Management SQLite Store](/selfhosted/sqlite-store)
- [Management Postgres Store](/selfhosted/postgres-store)