Merge pull request #2459 from alexbelgium/codex/simplify-netbird-server-addon-configuration

Simplify NetBird Server add-on configuration defaults
2026-03-25 23:41:45 +01:00 · 2026-02-06 16:28:56 +01:00
parent 58b7628c32 c4bb22f7ee
commit dcc8c1d3da
8 changed files with 87 additions and 137 deletions
--- a/netbird-server/DOCS.md
+++ b/netbird-server/DOCS.md
@@ -1,6 +1,6 @@
 # NetBird Server (monolithic)

-This add-on runs the NetBird self-hosted server stack in a single container (Management + Signal + Dashboard + Coturn; Relay optional). It does **not** use Home Assistant ingress. Access the Dashboard directly via the configured port.
+This add-on runs the NetBird self-hosted server stack in a single container (Management + Signal + Dashboard + Coturn). It does **not** use Home Assistant ingress. Access the Dashboard directly via the configured port.

 NetBird relies on gRPC. If you place the Management/Signal endpoints behind a reverse proxy, it **must** support HTTP/2 + gRPC proxying. See the NetBird reverse-proxy guide for supported configurations: <https://docs.netbird.io/selfhosted/reverse-proxy>.

@@ -11,22 +11,20 @@ The Dashboard container requires the `NETBIRD_MGMT_API_ENDPOINT` environment var
 ## Quick start

 1. Install the add-on.
-2. Configure your Identity Provider (IdP) and set the required `auth_*` options (or edit the generated `management.json`).
-3. Start the add-on and verify all services are running in the log output.
-4. Access the dashboard at `http://<HA_HOST>:<dashboard_port>`.
-
-> **Tip:** If you are using your own reverse proxy, set `external_base_url` to the public URL and keep TLS termination in your proxy.
+2. Start the add-on and verify all services are running in the log output.
+3. Stop the add-on, edit the generated `management.json` to configure your Identity Provider (IdP).
+4. Update `/config/netbird/dashboard/env` with the `NETBIRD_MGMT_API_ENDPOINT` and `AUTH_*` values for the dashboard.
+5. Start the add-on again and access the dashboard at `http://<HA_HOST>:8080`.

 ## Configuration

-### Required options
- `data_dir`: Where NetBird stores persistent data. Default: `/config/netbird`.
- `auth_authority`, `auth_client_id`, `auth_audience`, `auth_jwt_certs`, `auth_oidc_configuration_endpoint`: OIDC values used by the Management service and Dashboard.
+This add-on starts with zero configuration options. It writes default configs into `/config/netbird` and runs on the standard NetBird ports.

-### Optional options
- `disable_dashboard`: Disable the dashboard service entirely.
- `enable_relay`: Enable the NetBird relay service (requires `relay_exposed_address` and `relay_auth_secret`).
- `turn_external_ip`: Public IP to advertise when Coturn is behind NAT.
+### Dashboard environment overrides
+Edit `/config/netbird/dashboard/env` to configure the dashboard UI:
+
+- `NETBIRD_MGMT_API_ENDPOINT`: Public URL of the management API (for example, `https://netbird.example.com`).
+- `AUTH_AUTHORITY`, `AUTH_CLIENT_ID`, `AUTH_CLIENT_SECRET`, `AUTH_AUDIENCE`, `AUTH_SUPPORTED_SCOPES`, `USE_AUTH0`: OIDC settings for the dashboard UI.

 ### Generated configuration
 On first start, the add-on creates:
@@ -43,14 +41,9 @@ Default ports exposed by this add-on:
 - `10000/tcp`: Signal gRPC
 - `8080/tcp`: Dashboard
 - `3478/udp`: Coturn STUN/TURN
- `33080/tcp`: Relay (optional)

 If you have legacy (< v0.29) clients, review the legacy port notes in the NetBird self-hosted guide and ensure your firewall/forwarding rules are compatible.

-## Logs
-
-Use `log_level: debug` for more verbose logging.
-
 ## Notes

 - This add-on does **not** handle TLS certificates. Place it behind your existing reverse proxy if you need HTTPS.
--- a/netbird-server/config.yaml
+++ b/netbird-server/config.yaml
@@ -8,84 +8,18 @@ ingress: false
 map:
  - addon_config:rw
 name: NetBird Server
-options:
-  data_dir: /config/netbird
-  domain: ""
-  external_base_url: ""
-  management_listen: "0.0.0.0:33073"
-  signal_listen: "0.0.0.0:10000"
-  dashboard_listen: "0.0.0.0:8080"
-  turn_listen_port: 3478
-  turn_realm: "netbird"
-  turn_external_ip: ""
-  turn_min_port: 49152
-  turn_max_port: 65535
-  turn_user: "netbird"
-  turn_password: ""
-  idp_manager_type: "none"
-  auth_authority: ""
-  auth_client_id: ""
-  auth_client_secret: ""
-  auth_audience: ""
-  auth_supported_scopes: "openid profile email api offline_access email_verified"
-  auth_jwt_certs: ""
-  auth_user_id_claim: "sub"
-  auth_oidc_configuration_endpoint: ""
-  auth_token_endpoint: ""
-  use_auth0: false
-  idp_client_id: ""
-  idp_client_secret: ""
-  disable_default_policy: false
-  log_level: info
-  disable_dashboard: false
-  enable_relay: false
-  relay_exposed_address: ""
-  relay_auth_secret: ""
-schema:
-  data_dir: str
-  domain: str?
-  external_base_url: str?
-  management_listen: str
-  signal_listen: str
-  dashboard_listen: str
-  turn_listen_port: port
-  turn_realm: str
-  turn_external_ip: str?
-  turn_min_port: port
-  turn_max_port: port
-  turn_user: str
-  turn_password: str?
-  idp_manager_type: str
-  auth_authority: str?
-  auth_client_id: str?
-  auth_client_secret: str?
-  auth_audience: str?
-  auth_supported_scopes: str?
-  auth_jwt_certs: str?
-  auth_user_id_claim: str
-  auth_oidc_configuration_endpoint: str?
-  auth_token_endpoint: str?
-  use_auth0: bool
-  idp_client_id: str?
-  idp_client_secret: str?
-  disable_default_policy: bool
-  log_level: list(info|debug)
-  disable_dashboard: bool
-  enable_relay: bool
-  relay_exposed_address: str?
-  relay_auth_secret: str?
+options: {}
+schema: {}
 slug: netbird-server
 ports:
  33073/tcp: 33073
  10000/tcp: 10000
  8080/tcp: 8080
  3478/udp: 3478
-  33080/tcp: 33080
 ports_description:
  33073/tcp: Management API (HTTP/gRPC)
  10000/tcp: Signal gRPC
  8080/tcp: NetBird Dashboard (HTTP)
  3478/udp: Coturn STUN/TURN
-  33080/tcp: Relay (WebSocket/QUIC)
 url: https://github.com/alexbelgium/hassio-addons
 version: 0.64.5-1
--- a/netbird-server/rootfs/etc/cont-init.d/00-config.sh
+++ b/netbird-server/rootfs/etc/cont-init.d/00-config.sh
@@ -33,45 +33,39 @@ extract_port() {
  echo "${address##*:}"
 }

-DATA_DIR=$(bashio::config 'data_dir')
-DOMAIN=$(bashio::config 'domain')
-EXTERNAL_BASE_URL=$(bashio::config 'external_base_url')
-MANAGEMENT_LISTEN=$(bashio::config 'management_listen')
-SIGNAL_LISTEN=$(bashio::config 'signal_listen')
-DASHBOARD_LISTEN=$(bashio::config 'dashboard_listen')
-TURN_LISTEN_PORT=$(bashio::config 'turn_listen_port')
-TURN_REALM=$(bashio::config 'turn_realm')
-TURN_EXTERNAL_IP=$(bashio::config 'turn_external_ip')
-TURN_MIN_PORT=$(bashio::config 'turn_min_port')
-TURN_MAX_PORT=$(bashio::config 'turn_max_port')
-TURN_USER=$(bashio::config 'turn_user')
-TURN_PASSWORD=$(bashio::config 'turn_password')
-IDP_MANAGER_TYPE=$(bashio::config 'idp_manager_type')
-AUTH_AUTHORITY=$(bashio::config 'auth_authority')
-AUTH_AUDIENCE=$(bashio::config 'auth_audience')
-AUTH_JWT_CERTS=$(bashio::config 'auth_jwt_certs')
-AUTH_USER_ID_CLAIM=$(bashio::config 'auth_user_id_claim')
-AUTH_OIDC_CONFIGURATION_ENDPOINT=$(bashio::config 'auth_oidc_configuration_endpoint')
-AUTH_TOKEN_ENDPOINT=$(bashio::config 'auth_token_endpoint')
-IDP_CLIENT_ID=$(bashio::config 'idp_client_id')
-IDP_CLIENT_SECRET=$(bashio::config 'idp_client_secret')
-DISABLE_DEFAULT_POLICY=$(bashio::config 'disable_default_policy')
-DISABLE_DASHBOARD=$(bashio::config 'disable_dashboard')
-ENABLE_RELAY=$(bashio::config 'enable_relay')
-RELAY_EXPOSED_ADDRESS=$(bashio::config 'relay_exposed_address')
-RELAY_AUTH_SECRET=$(bashio::config 'relay_auth_secret')
+DATA_DIR="/config/netbird"
+DOMAIN="localhost"
+MANAGEMENT_LISTEN="0.0.0.0:33073"
+SIGNAL_LISTEN="0.0.0.0:10000"
+DASHBOARD_LISTEN="0.0.0.0:8080"
+TURN_LISTEN_PORT=3478
+TURN_REALM="netbird"
+TURN_EXTERNAL_IP=""
+TURN_MIN_PORT=49152
+TURN_MAX_PORT=65535
+TURN_USER="netbird"
+TURN_PASSWORD=""
+IDP_MANAGER_TYPE="none"
+AUTH_AUTHORITY=""
+AUTH_AUDIENCE=""
+AUTH_JWT_CERTS=""
+AUTH_USER_ID_CLAIM="sub"
+AUTH_OIDC_CONFIGURATION_ENDPOINT=""
+AUTH_TOKEN_ENDPOINT=""
+IDP_CLIENT_ID=""
+IDP_CLIENT_SECRET=""
+DISABLE_DEFAULT_POLICY=false
+DISABLE_DASHBOARD=false
+ENABLE_RELAY=false
+RELAY_EXPOSED_ADDRESS=""
+RELAY_AUTH_SECRET=""

 MANAGEMENT_PORT=$(extract_port "$MANAGEMENT_LISTEN")
 SIGNAL_PORT=$(extract_port "$SIGNAL_LISTEN")
 DASHBOARD_PORT=$(extract_port "$DASHBOARD_LISTEN")

-if [[ -z "$DOMAIN" ]]; then
-  DOMAIN="localhost"
-  bashio::log.warning "domain is empty; defaulting to localhost in generated configs."
-fi
-
 if [[ -z "$AUTH_AUTHORITY" || -z "$AUTH_AUDIENCE" || -z "$AUTH_JWT_CERTS" ]]; then
-  bashio::log.warning "OIDC configuration is incomplete. Update auth_* options or edit ${DATA_DIR}/management/management.json."
+  bashio::log.warning "OIDC configuration is incomplete. Edit ${DATA_DIR}/management/management.json to finish setup."
 fi

 mkdir -p "$DATA_DIR" \
@@ -216,3 +210,21 @@ sed "s/__DASHBOARD_PORT__/${DASHBOARD_PORT}/g" \

 mkdir -p /run/nginx
 chmod +x /usr/local/bin/init_react_envs.sh
+
+# Generate dashboard env file if missing
+DASHBOARD_ENV_FILE="$DATA_DIR/dashboard/env"
+if [[ ! -f "$DASHBOARD_ENV_FILE" ]]; then
+  bashio::log.info "Generating dashboard env file at ${DASHBOARD_ENV_FILE}."
+  cat <<'ENV' > "$DASHBOARD_ENV_FILE"
+# NetBird dashboard environment overrides.
+# Example: NETBIRD_MGMT_API_ENDPOINT="https://netbird.example.com"
+NETBIRD_MGMT_API_ENDPOINT=""
+AUTH_AUTHORITY=""
+AUTH_CLIENT_ID=""
+AUTH_CLIENT_SECRET=""
+AUTH_AUDIENCE=""
+AUTH_SUPPORTED_SCOPES="openid profile email api offline_access email_verified"
+USE_AUTH0="false"
+ENV
+  chmod 600 "$DASHBOARD_ENV_FILE"
+fi
--- a/netbird-server/rootfs/etc/services.d/coturn/run
+++ b/netbird-server/rootfs/etc/services.d/coturn/run
@@ -7,7 +7,7 @@ set -euo pipefail
 # Runs Coturn
 # ==============================================================================

-DATA_DIR=$(bashio::config 'data_dir')
+DATA_DIR="/config/netbird"
 TURN_CONFIG="$DATA_DIR/turn/turnserver.conf"

 if [[ ! -f "$TURN_CONFIG" ]]; then
--- a/netbird-server/rootfs/etc/services.d/dashboard/run
+++ b/netbird-server/rootfs/etc/services.d/dashboard/run
@@ -7,19 +7,30 @@ set -euo pipefail
 # Runs the NetBird Dashboard
 # ==============================================================================

-DOMAIN=$(bashio::config 'domain')
-EXTERNAL_BASE_URL=$(bashio::config 'external_base_url')
-MANAGEMENT_LISTEN=$(bashio::config 'management_listen')
-AUTH_AUTHORITY=$(bashio::config 'auth_authority')
-AUTH_CLIENT_ID=$(bashio::config 'auth_client_id')
-AUTH_CLIENT_SECRET=$(bashio::config 'auth_client_secret')
-AUTH_AUDIENCE=$(bashio::config 'auth_audience')
-AUTH_SUPPORTED_SCOPES=$(bashio::config 'auth_supported_scopes')
-USE_AUTH0=$(bashio::config 'use_auth0')
+DOMAIN="localhost"
+EXTERNAL_BASE_URL=""
+MANAGEMENT_LISTEN="0.0.0.0:33073"
+AUTH_AUTHORITY=""
+AUTH_CLIENT_ID=""
+AUTH_CLIENT_SECRET=""
+AUTH_AUDIENCE=""
+AUTH_SUPPORTED_SCOPES="openid profile email api offline_access email_verified"
+USE_AUTH0="false"
+NETBIRD_MGMT_API_ENDPOINT=""

 MANAGEMENT_PORT="${MANAGEMENT_LISTEN##*:}"

-if [[ -n "$EXTERNAL_BASE_URL" ]]; then
+ENV_FILE="/config/netbird/dashboard/env"
+if [[ -f "$ENV_FILE" ]]; then
+  set -a
+  # shellcheck disable=SC1090
+  . "$ENV_FILE"
+  set +a
+fi
+
+if [[ -n "$NETBIRD_MGMT_API_ENDPOINT" ]]; then
+  NETBIRD_MGMT_API_ENDPOINT="$NETBIRD_MGMT_API_ENDPOINT"
+elif [[ -n "$EXTERNAL_BASE_URL" ]]; then
  NETBIRD_MGMT_API_ENDPOINT="$EXTERNAL_BASE_URL"
 elif [[ -n "$DOMAIN" ]]; then
  NETBIRD_MGMT_API_ENDPOINT="http://${DOMAIN}:${MANAGEMENT_PORT}"
--- a/netbird-server/rootfs/etc/services.d/management/run
+++ b/netbird-server/rootfs/etc/services.d/management/run
@@ -7,8 +7,8 @@ set -euo pipefail
 # Runs the NetBird Management service
 # ==============================================================================

-DATA_DIR=$(bashio::config 'data_dir')
-LOG_LEVEL=$(bashio::config 'log_level')
+DATA_DIR="/config/netbird"
+LOG_LEVEL="info"
 MANAGEMENT_CONFIG="$DATA_DIR/management/management.json"

 if [[ ! -f "$MANAGEMENT_CONFIG" ]]; then
--- a/netbird-server/rootfs/etc/services.d/relay/run
+++ b/netbird-server/rootfs/etc/services.d/relay/run
@@ -7,9 +7,9 @@ set -euo pipefail
 # Runs the NetBird Relay (optional)
 # ==============================================================================

-LOG_LEVEL=$(bashio::config 'log_level')
-RELAY_EXPOSED_ADDRESS=$(bashio::config 'relay_exposed_address')
-RELAY_AUTH_SECRET=$(bashio::config 'relay_auth_secret')
+LOG_LEVEL="info"
+RELAY_EXPOSED_ADDRESS=""
+RELAY_AUTH_SECRET=""

 bashio::log.info "Starting NetBird Relay..."
 exec /usr/local/bin/netbird-relay \
--- a/netbird-server/rootfs/etc/services.d/signal/run
+++ b/netbird-server/rootfs/etc/services.d/signal/run
@@ -7,8 +7,8 @@ set -euo pipefail
 # Runs the NetBird Signal service
 # ==============================================================================

-SIGNAL_LISTEN=$(bashio::config 'signal_listen')
-LOG_LEVEL=$(bashio::config 'log_level')
+SIGNAL_LISTEN="0.0.0.0:10000"
+LOG_LEVEL="info"
 SIGNAL_PORT="${SIGNAL_LISTEN##*:}"

 bashio::log.info "Starting NetBird Signal on port ${SIGNAL_PORT}..."