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

Simplify NetBird Server add-on configuration defaults

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`).
+2. Start the add-on and verify all services are running in the log output.
-3. 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. Access the dashboard at `http://<HA_HOST>:<dashboard_port>`.
+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`.
-> **Tip:** If you are using your own reverse proxy, set `external_base_url` to the public URL and keep TLS termination in your proxy.
 
 ## Configuration
 
-### Required options
+This add-on starts with zero configuration options. It writes default configs into `/config/netbird` and runs on the standard NetBird ports.
-- `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.
 
-### Optional options
+### Dashboard environment overrides
-- `disable_dashboard`: Disable the dashboard service entirely.
+Edit `/config/netbird/dashboard/env` to configure the dashboard UI:
-- `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.
+- `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.

netbird-server/config.yaml

@@ -8,84 +8,18 @@ ingress: false
 map:
   - addon_config:rw
 name: NetBird Server
-options:
+options: {}
-  data_dir: /config/netbird
+schema: {}
-  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?
 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

netbird-server/rootfs/etc/cont-init.d/00-config.sh

@@ -33,45 +33,39 @@ extract_port() {
   echo "${address##*:}"
 }
 
-DATA_DIR=$(bashio::config 'data_dir')
+DATA_DIR="/config/netbird"
-DOMAIN=$(bashio::config 'domain')
+DOMAIN="localhost"
-EXTERNAL_BASE_URL=$(bashio::config 'external_base_url')
+MANAGEMENT_LISTEN="0.0.0.0:33073"
-MANAGEMENT_LISTEN=$(bashio::config 'management_listen')
+SIGNAL_LISTEN="0.0.0.0:10000"
-SIGNAL_LISTEN=$(bashio::config 'signal_listen')
+DASHBOARD_LISTEN="0.0.0.0:8080"
-DASHBOARD_LISTEN=$(bashio::config 'dashboard_listen')
+TURN_LISTEN_PORT=3478
-TURN_LISTEN_PORT=$(bashio::config 'turn_listen_port')
+TURN_REALM="netbird"
-TURN_REALM=$(bashio::config 'turn_realm')
+TURN_EXTERNAL_IP=""
-TURN_EXTERNAL_IP=$(bashio::config 'turn_external_ip')
+TURN_MIN_PORT=49152
-TURN_MIN_PORT=$(bashio::config 'turn_min_port')
+TURN_MAX_PORT=65535
-TURN_MAX_PORT=$(bashio::config 'turn_max_port')
+TURN_USER="netbird"
-TURN_USER=$(bashio::config 'turn_user')
+TURN_PASSWORD=""
-TURN_PASSWORD=$(bashio::config 'turn_password')
+IDP_MANAGER_TYPE="none"
-IDP_MANAGER_TYPE=$(bashio::config 'idp_manager_type')
+AUTH_AUTHORITY=""
-AUTH_AUTHORITY=$(bashio::config 'auth_authority')
+AUTH_AUDIENCE=""
-AUTH_AUDIENCE=$(bashio::config 'auth_audience')
+AUTH_JWT_CERTS=""
-AUTH_JWT_CERTS=$(bashio::config 'auth_jwt_certs')
+AUTH_USER_ID_CLAIM="sub"
-AUTH_USER_ID_CLAIM=$(bashio::config 'auth_user_id_claim')
+AUTH_OIDC_CONFIGURATION_ENDPOINT=""
-AUTH_OIDC_CONFIGURATION_ENDPOINT=$(bashio::config 'auth_oidc_configuration_endpoint')
+AUTH_TOKEN_ENDPOINT=""
-AUTH_TOKEN_ENDPOINT=$(bashio::config 'auth_token_endpoint')
+IDP_CLIENT_ID=""
-IDP_CLIENT_ID=$(bashio::config 'idp_client_id')
+IDP_CLIENT_SECRET=""
-IDP_CLIENT_SECRET=$(bashio::config 'idp_client_secret')
+DISABLE_DEFAULT_POLICY=false
-DISABLE_DEFAULT_POLICY=$(bashio::config 'disable_default_policy')
+DISABLE_DASHBOARD=false
-DISABLE_DASHBOARD=$(bashio::config 'disable_dashboard')
+ENABLE_RELAY=false
-ENABLE_RELAY=$(bashio::config 'enable_relay')
+RELAY_EXPOSED_ADDRESS=""
-RELAY_EXPOSED_ADDRESS=$(bashio::config 'relay_exposed_address')
+RELAY_AUTH_SECRET=""
-RELAY_AUTH_SECRET=$(bashio::config '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

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

netbird-server/rootfs/etc/services.d/dashboard/run

@@ -7,19 +7,30 @@ set -euo pipefail
 # Runs the NetBird Dashboard
 # ==============================================================================
 
-DOMAIN=$(bashio::config 'domain')
+DOMAIN="localhost"
-EXTERNAL_BASE_URL=$(bashio::config 'external_base_url')
+EXTERNAL_BASE_URL=""
-MANAGEMENT_LISTEN=$(bashio::config 'management_listen')
+MANAGEMENT_LISTEN="0.0.0.0:33073"
-AUTH_AUTHORITY=$(bashio::config 'auth_authority')
+AUTH_AUTHORITY=""
-AUTH_CLIENT_ID=$(bashio::config 'auth_client_id')
+AUTH_CLIENT_ID=""
-AUTH_CLIENT_SECRET=$(bashio::config 'auth_client_secret')
+AUTH_CLIENT_SECRET=""
-AUTH_AUDIENCE=$(bashio::config 'auth_audience')
+AUTH_AUDIENCE=""
-AUTH_SUPPORTED_SCOPES=$(bashio::config 'auth_supported_scopes')
+AUTH_SUPPORTED_SCOPES="openid profile email api offline_access email_verified"
-USE_AUTH0=$(bashio::config 'use_auth0')
+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}"

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')
+DATA_DIR="/config/netbird"
-LOG_LEVEL=$(bashio::config 'log_level')
+LOG_LEVEL="info"
 MANAGEMENT_CONFIG="$DATA_DIR/management/management.json"
 
 if [[ ! -f "$MANAGEMENT_CONFIG" ]]; then

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')
+LOG_LEVEL="info"
-RELAY_EXPOSED_ADDRESS=$(bashio::config 'relay_exposed_address')
+RELAY_EXPOSED_ADDRESS=""
-RELAY_AUTH_SECRET=$(bashio::config 'relay_auth_secret')
+RELAY_AUTH_SECRET=""
 
 bashio::log.info "Starting NetBird Relay..."
 exec /usr/local/bin/netbird-relay \

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')
+SIGNAL_LISTEN="0.0.0.0:10000"
-LOG_LEVEL=$(bashio::config 'log_level')
+LOG_LEVEL="info"
 SIGNAL_PORT="${SIGNAL_LISTEN##*:}"
 
 bashio::log.info "Starting NetBird Signal on port ${SIGNAL_PORT}..."