Server Configuration
Nebula Commander is configured with environment variables. All backend settings use the prefix NEBULA_COMMANDER_. You can configure everything from the docs below.
- Environment variables – Full list: database, JWT, OIDC, CORS, session, SMTP, debug. Use this to configure the backend completely.
- OIDC – Log in with Keycloak or another OIDC provider: issuer URLs (internal vs public), client id/secret, redirect URI, and zero-touch vs manual setup.
Two-tier layout (Docker)
When using Docker:
- Infrastructure –
docker/.env: ports (e.g. frontend, backend, Keycloak), optional JWT_SECRET_FILE path. - Backend –
docker/env.d/backend: every NEBULA_COMMANDER_* variable. Copy from env.d.example/backend and edit.
See Installation: Docker for the copy steps.
NixOS
NixOS options (port, backendPort, databasePath, certStorePath, jwtSecretFile, debug) are documented in Installation: NixOS. For OIDC and other backend-only settings, extend the service environment or point the backend at a config file if your setup supports it.
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
| Variable | Description | Default |
|---|
NEBULA_COMMANDER_DEBUG | Enable debug mode (enables dev-token endpoint; do not use in production) | false |
Database
| Variable | Description | Default |
|---|
NEBULA_COMMANDER_DATABASE_URL | Database URL (SQLite: use four slashes for absolute path, e.g. sqlite+aiosqlite:////var/lib/nebula-commander/db.sqlite) | sqlite+aiosqlite:////var/lib/nebula-commander/db.sqlite |
NEBULA_COMMANDER_DATABASE_PATH | Override for SQLite path | — |
NEBULA_COMMANDER_CERT_STORE_PATH | Directory for CA and host certificates | /var/lib/nebula-commander/certs |
JWT
| Variable | Description | Default |
|---|
NEBULA_COMMANDER_JWT_SECRET_KEY | Secret for signing tokens (generate with e.g. openssl rand -base64 32) | change-this-in-production |
NEBULA_COMMANDER_JWT_SECRET_FILE | Path to file containing JWT secret (overrides secret key when present) | — |
NEBULA_COMMANDER_JWT_ALGORITHM | JWT algorithm | HS256 |
NEBULA_COMMANDER_JWT_EXPIRATION_MINUTES | Token expiration in minutes | 1440 (24 hours) |
Public URL and OIDC
| Variable | Description | Default |
|---|
NEBULA_COMMANDER_PUBLIC_URL | Base URL where users reach the app (FQDN or host:port). Used to derive redirect URI and for redirect validation. | — |
NEBULA_COMMANDER_OIDC_ISSUER_URL | OIDC issuer URL used by the backend to reach the provider (internal; e.g. http://keycloak:8080/realms/nebula-commander) | — |
NEBULA_COMMANDER_OIDC_PUBLIC_ISSUER_URL | OIDC issuer URL as seen by the browser (FQDN or host:port) | — |
NEBULA_COMMANDER_OIDC_CLIENT_ID | OIDC client ID | — |
NEBULA_COMMANDER_OIDC_CLIENT_SECRET | OIDC client secret | — |
NEBULA_COMMANDER_OIDC_CLIENT_SECRET_FILE | Path to file containing OIDC client secret | — |
NEBULA_COMMANDER_OIDC_REDIRECT_URI | Callback URL (optional; derived as PUBLIC_URL + /api/auth/callback when PUBLIC_URL is set) | — |
NEBULA_COMMANDER_OIDC_SCOPES | OIDC scopes (space-separated) | openid profile email |
CORS and session
| Variable | Description | Default |
|---|
NEBULA_COMMANDER_CORS_ORIGINS | Allowed CORS origins: * or comma-separated list. Include your public app URL. Using * with credentials is insecure. | http://localhost:3000, http://localhost:5173 |
NEBULA_COMMANDER_SESSION_HTTPS_ONLY | Set session cookie to HTTPS-only (use true in production with HTTPS) | false |
NEBULA_COMMANDER_ALLOWED_REDIRECT_HOSTS | Allowed hosts for OAuth/OIDC redirects (comma-separated). When empty and PUBLIC_URL is set, derived from PUBLIC_URL. | — |
Certificates and device tokens
| Variable | Description | Default |
|---|
NEBULA_COMMANDER_DEFAULT_CERT_EXPIRY_DAYS | Default certificate expiry in days | 365 |
NEBULA_COMMANDER_DEVICE_TOKEN_EXPIRATION_DAYS | Device token (enrollment) expiry in days | 3650 |
SMTP (optional)
| Variable | Description | Default |
|---|
NEBULA_COMMANDER_SMTP_ENABLED | Enable sending email (e.g. for invitations) | false |
NEBULA_COMMANDER_SMTP_HOST | SMTP host | localhost |
NEBULA_COMMANDER_SMTP_PORT | SMTP port | 587 |
NEBULA_COMMANDER_SMTP_USERNAME | SMTP username | — |
NEBULA_COMMANDER_SMTP_PASSWORD | SMTP password | — |
NEBULA_COMMANDER_SMTP_PASSWORD_FILE | Path to file containing SMTP password | — |
NEBULA_COMMANDER_SMTP_USE_TLS | Use TLS | true |
NEBULA_COMMANDER_SMTP_FROM_EMAIL | From address | noreply@example.com |
NEBULA_COMMANDER_SMTP_FROM_NAME | From name | Nebula Commander |
Server (advanced)
| Variable | Description | Default |
|---|
NEBULA_COMMANDER_HOST | Bind host | 0.0.0.0 |
NEBULA_COMMANDER_PORT | Bind port | 8081 |
Security notes
- Generate a strong JWT secret for production (e.g.
openssl rand -base64 32). Do not use the default. - Prefer
*_FILE options (JWT, 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
- Copy example env files and edit
env.d/backend (set PUBLIC_URL, OIDC issuer URLs, client id/secret). - Start with Keycloak:
docker compose -f docker-compose.yml -f docker-compose-keycloak.yml up -d - 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
Use the same variables. 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). Run without the Keycloak compose file.
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.