Server Configuration

• 1: Environment Variables
• 2: OIDC Authentication

1 - Environment Variables

All backend settings use the NEBULA_COMMANDER_ prefix. Set them in the environment or in a file (e.g. docker/env.d/backend). Optional values can be omitted; defaults apply.

Application

Database

Encryption at rest

Required. The backend refuses to boot if this is left at a placeholder/unset value — unlike most settings here, there’s no insecure-but-working default.

JWT

Public URL and OIDC

CORS and session

Certificates and device tokens

SMTP (optional)

Analytics (optional)

Exposed publicly via GET /api/public-config (no auth) so the frontend can inject the corresponding script tags.

Server (advanced)

Security notes

• Generate a strong JWT secret for production (e.g. openssl rand -base64 32). Do not use the default.
• ENCRYPTION_KEY has no default to leave-unset-and-forget — the backend won’t start without one. Generate it once and keep it: losing it makes every stored certificate/private key unrecoverable.
• Prefer *_FILE options (JWT, encryption key, OIDC secret, SMTP password) over plain env vars when possible.
• In production: set DEBUG=false, use HTTPS for PUBLIC_URL and OIDC, and set CORS_ORIGINS to your actual frontend origin(s). For examples of putting Nebula Commander behind Nginx, Traefik, or Caddy with TLS and HSTS, see Reverse Proxy.

2 - OIDC Authentication

Nebula Commander can use OpenID Connect (OIDC) for login. Keycloak is supported with a pre-configured setup; other OIDC providers (Authentik, Auth0, etc.) work with the same environment variables.

Required variables

Set these in env.d/backend (Docker) or in the backend environment:

• NEBULA_COMMANDER_PUBLIC_URL – URL where users reach the app (FQDN or host:port). The redirect URI is derived as PUBLIC_URL + /api/auth/callback if you do not set OIDC_REDIRECT_URI.
• NEBULA_COMMANDER_OIDC_ISSUER_URL – Issuer URL used by the backend to talk to the provider. Inside Docker use the container name and container port (e.g. http://keycloak:8080/realms/nebula-commander). Do not use the host-mapped port here.
• NEBULA_COMMANDER_OIDC_PUBLIC_ISSUER_URL – Issuer URL as seen by the browser (FQDN or host:port). Use the same URL users would use to open the provider’s login page.
• NEBULA_COMMANDER_OIDC_CLIENT_ID – OIDC client ID (e.g. nebula-commander).
• NEBULA_COMMANDER_OIDC_CLIENT_SECRET – Client secret from the provider. Prefer NEBULA_COMMANDER_OIDC_CLIENT_SECRET_FILE in production.

Optional: NEBULA_COMMANDER_OIDC_REDIRECT_URI – Override only if you need a callback URL different from PUBLIC_URL + /api/auth/callback.

Keycloak with Docker

1. Copy example env files and edit env.d/backend (set PUBLIC_URL, OIDC issuer URLs, client id/secret).
2. Start with Keycloak:
   docker compose -f docker-compose.yml -f docker-compose-keycloak.yml up -d
3. Create a user in Keycloak Admin and assign client roles under the nebula-commander client: system-admin, network-owner, or user.

Zero-touch Keycloak

The project provides a custom Keycloak image that imports the realm and theme at startup. Build the image (see Installation: Docker and docker/keycloak), set the same OIDC variables in env.d/backend, and start the stack. No manual realm creation is required; create users and assign roles in the Admin console.

Manual Keycloak setup

If you do not use the zero-touch image, create the realm and client in Keycloak:

• Client type: OpenID Connect, confidential, standard flow.
• Valid redirect URI: your PUBLIC_URL + /api/auth/callback.
• Valid post-logout redirect URIs: PUBLIC_URL + /*.
• Web origins: your PUBLIC_URL.
• Create client roles: system-admin, network-owner, user. Assign them to users via Role mapping.

Then set the client secret in env.d/backend.

Backend cannot reach Keycloak

The backend talks to Keycloak on the Docker network. Use the container port in NEBULA_COMMANDER_OIDC_ISSUER_URL (e.g. http://keycloak:8080/realms/nebula-commander), not the host-mapped port. Use the host port or FQDN only in NEBULA_COMMANDER_OIDC_PUBLIC_ISSUER_URL and in NEBULA_COMMANDER_PUBLIC_URL.

External OIDC provider

Keycloak is the default, but Nebula Commander’s OIDC integration is fully provider-agnostic: login, logout, and step-up reauth all use standard OIDC discovery (.well-known/openid-configuration) to find the provider’s actual endpoints, rather than assuming Keycloak’s URL conventions. Any standards-compliant provider — Authentik, Auth0, Okta, and others — works with the same environment variables.

Use the same variables as above. In the provider, set redirect URI to PUBLIC_URL + /api/auth/callback, client type Confidential, grant type Authorization Code. Set OIDC_ISSUER_URL and OIDC_PUBLIC_ISSUER_URL to the provider’s issuer URL (often the same).

docker-compose.yml includes the Keycloak stack by default. To use an external provider instead, comment out (or delete) the include: block at the top of docker-compose.yml:

# include:
#   - path: ./docker-compose-keycloak.yml

then docker compose up -d starts only the backend and frontend.

Admin role mapping

Keycloak assigns roles via a client-roles claim shaped like resource_access.<client_id>.roles, which most other providers don’t emit by default. If you’re not using Keycloak, set:

• NEBULA_COMMANDER_OIDC_ADMIN_ROLE_CLAIM – the top-level claim your provider emits (e.g. roles, groups, or an Auth0-style namespaced claim like https://nebula.example.com/roles).
• NEBULA_COMMANDER_OIDC_ADMIN_ROLE_VALUE – the value within that claim that grants system-admin (default system-admin).

Leave OIDC_ADMIN_ROLE_CLAIM unset to keep using Keycloak’s default shape — this is the default, so existing Keycloak deployments need no changes.

Roles and permissions

• system-admin – Manage users; view all networks/nodes with limited data; delete networks/nodes (with reauth); request access grants from owners.
• network-owner – Create and manage networks, nodes, invitations, node requests, and access; set default node parameters and auto-approval.
• user – Access only what network owners grant; request nodes and higher access.

See the repository docker/README for detailed RBAC and permission features.