OpsNexus
DocsReference

Environment variables

Every server setting OpsNexus reads, with its default and what it does, grouped by area.

On this page

OpsNexus reads its server settings from environment variables. With Docker Compose they come from the .env file, which you create from .env.example. For a task-based guide to the most important settings, see Configuration.

How to read this page

  • Default is the built-in value the server uses when the variable is not set. Where .env.example sets a different value, it is shown in the In .env.example column.
  • Names are case-insensitive.
  • Lists are comma-separated.
  • Booleans accept true or false.
  • After you change .env, recreate the backend: docker compose up -d --force-recreate api worker scheduler.
Note

The compose file sets DATABASE_URL, REDIS_URL, VAULT_ADDR and VAULT_TOKEN_FILE for the api, worker and scheduler containers. Values for these four in .env are ignored. To change them, use a docker-compose.override.yml. See Running in production.

General

Variable Default In .env.example What it does
APP_NAME OpsNexus not set Application name, shown as the issuer in authenticator apps and in the API docs title.
ENVIRONMENT development production One of development, test, staging, production. In production, the API sends a Strict-Transport-Security header.
DEBUG false not set Turns on debug logging.
PUBLIC_URL http://localhost:8080 http://localhost:8080 The URL people open in the browser. Used for SSO redirect URIs, links in notifications, webhooks and agent install scripts.
AGENT_URL empty empty The URL build agents use to reach OpsNexus, embedded in install commands. Empty means PUBLIC_URL. Never use localhost or host.docker.internal.
CORS_ORIGINS http://localhost:5173,http://localhost:8080 http://localhost:8080 Browser origins allowed to call the API.

Security and sessions

Variable Default In .env.example What it does
SECRET_KEY a placeholder CHANGE-ME-... Signs sign-in tokens. Also derives the key that encrypts MFA seeds, Terraform state, webhook tokens and other stored values, unless LOCAL_SECRET_KEY is set. Must be long and random: openssl rand -hex 32. Do not change it after the first start.
ACCESS_TOKEN_MINUTES 15 15 Lifetime of an access token.
REFRESH_TOKEN_DAYS 7 7 Lifetime of a sign-in session (refresh token).
MFA_TOKEN_MINUTES 5 not set Time allowed to enter the MFA code after the password is accepted.

Database and cache

Variable Default In .env.example What it does
DATABASE_URL postgresql+psycopg://opsnexus:opsnexus@localhost:5432/opsnexus not set PostgreSQL connection string. Compose builds it from the POSTGRES_* values.
REDIS_URL redis://localhost:6379/0 not set Redis connection string, for the job queue, live updates and rate limiting. Compose sets redis://redis:6379/0.
POSTGRES_USER none opsnexus Used by compose for the db container and DATABASE_URL.
POSTGRES_PASSWORD none CHANGE-ME Used by compose for the db container and DATABASE_URL. Must be set.
POSTGRES_DB none opsnexus Used by compose for the db container and DATABASE_URL.

Secret storage

Variable Default In .env.example What it does
SECRET_BACKEND local vault vault stores secret values in HashiCorp Vault KV v2. local stores them encrypted in PostgreSQL and is for development only.
VAULT_ADDR http://localhost:8200 not set Vault address. Compose sets http://vault:8200.
VAULT_TOKEN empty not set A Vault token. Used first, if set.
VAULT_TOKEN_FILE empty not set A file containing the Vault token. Compose sets /vault-init/opsnexus.token, written by the vault-init service. Used when VAULT_TOKEN is empty.
VAULT_ROLE_ID empty not set AppRole role ID. Used when there is no token.
VAULT_SECRET_ID empty not set AppRole secret ID.
VAULT_MOUNT secret secret The KV v2 mount.
VAULT_PREFIX opsnexus opsnexus Path prefix for OpsNexus secrets in the mount.
LOCAL_SECRET_KEY empty not set A Fernet key for the local backend and for encrypted fields. Empty derives the key from SECRET_KEY. Generate one with python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())".

First admin

Read only on the first start, when the database has no organization.

Variable Default In .env.example What it does
BOOTSTRAP_ORG_NAME Default Organization Acme Corp Name of the organization.
BOOTSTRAP_ADMIN_EMAIL admin@example.com admin@example.com Email of the first admin (a super admin, username admin).
BOOTSTRAP_ADMIN_PASSWORD empty empty The first admin's password. Empty prints a random one-time password once in the API log.

Single sign-on

A provider is offered on the sign-in page only when its client ID and secret are both set. Redirect URIs are ${PUBLIC_URL}/api/auth/sso/google/callback and ${PUBLIC_URL}/api/auth/sso/microsoft/callback.

Variable Default In .env.example What it does
GOOGLE_CLIENT_ID empty empty Google OAuth client ID.
GOOGLE_CLIENT_SECRET empty empty Google OAuth client secret.
MICROSOFT_CLIENT_ID empty empty Microsoft Entra ID application (client) ID.
MICROSOFT_CLIENT_SECRET empty empty Microsoft Entra ID client secret.
MICROSOFT_TENANT_ID common common Microsoft Entra tenant ID.

Background jobs and retention

Variable Default In .env.example What it does
INTEGRATION_SYNC_MINUTES 5 5 How often pipelines and builds are imported from integrations.
AGENT_OFFLINE_SECONDS 120 120 An agent silent for longer is marked disconnected; after a further hour, offline.
METRIC_RETENTION_DAYS 30 30 How long agent metrics are kept.
TRAFFIC_RETENTION_DAYS 395 not set How long website traffic hits are kept.
DOMAIN_CHECK_RETENTION_DAYS 30 30 How long domain check results are kept.
REPORT_RETENTION_DAYS 90 not set How long generated report runs are kept.
CLOUD_SYNC_MINUTES 60 not set How often cloud accounts are synced.
CLOUD_COST_DAYS 90 not set How many days of cost data a cloud account sync fetches by default.
CLOUD_RESOURCE_COST_RETENTION_DAYS 400 not set How long per-resource daily cost history is kept.

Processes

These are read by the container entrypoint, not by the settings class.

Variable Default In .env.example What it does
API_WORKERS 2 2 Number of API (uvicorn) worker processes in the api container.
WORKER_CONCURRENCY 4 4 Number of jobs one worker container runs at the same time.

Monitoring, domains and notifications

Variable Default In .env.example What it does
ALLOW_PRIVATE_TARGETS false false Lets domain checks and webhooks reach private and internal addresses (10.x, 192.168.x, localhost). Keep false unless you monitor internal services: it protects against SSRF.
PAGESPEED_API_KEY empty empty Optional Google PageSpeed Insights API key, to add Core Web Vitals to SEO reports.
GEOIP_DIR /app/geoip not set Where the DB-IP Lite country database is downloaded. A volume in compose.

Files and artifacts

Variable Default In .env.example What it does
BACKUP_DIR /app/backups not set Where in-app backup files are written in the API container. A volume in compose.
ARTIFACT_DIR /app/artifacts not set Where files archived by pipeline runs are stored. A volume in compose.
ARTIFACT_MAX_MB 100 not set Maximum size of one artifact file, in MB.
ARTIFACT_MAX_FILES 200 not set Maximum number of artifact files per pipeline run.
AGENT_DIST_DIR ../agent not set Folder with the agent program and install scripts served for download. The image sets /app/agent.
Note

The bundled web container accepts artifact uploads up to 110 MB. Raising ARTIFACT_MAX_MB above that also needs a change to frontend/nginx.conf, and to any reverse proxy in front of OpsNexus.

Servers, SSH and Remote Desktop

Variable Default In .env.example What it does
TERMINAL_IDLE_MINUTES 30 30 A browser SSH terminal closes after this many minutes without keyboard input.
TERMINAL_MAX_HOURS 8 8 Maximum length of a terminal session.
TERMINAL_CONNECT_TIMEOUT_SECONDS 15 15 Timeout when connecting to a server.
GUACD_HOST guacd not set Host of the Apache Guacamole guacd proxy used for Remote Desktop (RDP).
GUACD_PORT 4822 not set Port of guacd.

Testing only

Variable Default What it does
INFRA_OFFLINE_PROVIDER false Infra designer test mode: Terraform runs use fake AWS credentials and skip validation. Never enable it in a real deployment.
TEST_DATABASE_URL postgresql+psycopg://opsnexus:opsnexus@localhost:5432/opsnexus_test Database for the backend test suite. The tests may wipe it.

Docker Compose

These variables are read by docker-compose.yml itself, not by the server.

Variable Default What it does
WEB_PORT 8080 Host port for the web container. Can include an address, for example 127.0.0.1:8080.
VAULT_HOST_PORT 18200 Host port for the Vault UI, bound to 127.0.0.1 only.
RUNNER_TOKEN empty Registration token for the optional runner build agent (docker compose --profile runner up -d runner).
RUNNER_NAME docker-runner Name of the runner agent.
RUNNER_EXECUTORS 2 Number of pipeline runs the runner agent takes at once.
RUNNER_LABELS linux,docker-runner Labels of the runner agent.

Build agent

The agent (onx_agent.py) reads these on the machine or container where it runs. The compose runner service sets them from the RUNNER_* values above.

Variable What it does
ONX_URL OpsNexus address. Always overrides the address saved at registration.
ONX_REGISTRATION_TOKEN Single-use registration token (onx_reg_...). Used by onx_agent.py start when there is no config yet, or when the token differs from the one the config came from.
ONX_AGENT_NAME Agent name used when registering.
ONX_EXECUTORS How many pipeline runs at the same time. 0 means monitoring only. With start, the default is 2.
ONX_LABELS Comma-separated labels pipelines use to pick the agent.
ONX_WORK_DIR Folder for build workspaces.
ONX_AGENT_CONFIG Path of the agent's config file, to use another location.

See Build agents.