OpsNexus
DocsGetting started

Configuration

The settings you are most likely to change, grouped by task, and how to apply them.

On this page

OpsNexus reads its server settings from environment variables. With Docker Compose they come from the .env file in the repository root, which you create from .env.example. This page covers the settings you are most likely to change. For every setting and its default, see Environment variables.

Many other options, such as the password policy, notification channels and backup schedules, are set in the app, not in .env. They are covered on the pages for those modules.

How settings are applied

  • Setting names are case-insensitive. .env.example uses upper case.
  • The API, worker and scheduler containers all read the same .env file.
  • Lists, such as CORS_ORIGINS, are comma-separated.

After you change .env, recreate the backend containers:

bash
docker compose up -d --force-recreate api worker scheduler

If you changed WEB_PORT or VAULT_HOST_PORT, also recreate the service that publishes the port:

bash
docker compose up -d --force-recreate web vault
Note

The compose file sets DATABASE_URL, REDIS_URL, VAULT_ADDR and VAULT_TOKEN_FILE for the backend containers itself, so those values in .env are ignored. To point OpsNexus at your own database or Vault, see Running in production.

Set the address of OpsNexus

Setting Default in .env.example What it does
PUBLIC_URL http://localhost:8080 The URL people open in the browser. Used for SSO redirects, links in notifications and webhooks.
AGENT_URL empty The URL build agents use to reach OpsNexus. Empty means PUBLIC_URL.
CORS_ORIGINS http://localhost:8080 Browser origins allowed to call the API. Set it to the same origin as PUBLIC_URL.
WEB_PORT 8080 The host port the web container is published on.

Set AGENT_URL when PUBLIC_URL is localhost (or a name only browsers can resolve) but agents run on other machines. Use an address every agent can reach, for example:

ini
PUBLIC_URL=http://localhost:8080
AGENT_URL=http://192.168.1.10:8080
Warning

Never set AGENT_URL to localhost or host.docker.internal. Agents on other machines cannot reach those addresses. Open WEB_PORT in the server's firewall.

The install commands under Build agents → Download & install use this address. You can also edit the OpsNexus address field there before you copy a command.

Secure sign-in

Setting Default What it does
SECRET_KEY none (you must set it) Signs sign-in tokens. Also used to encrypt MFA seeds, stored Terraform state and other values in the database, unless LOCAL_SECRET_KEY is set.
ACCESS_TOKEN_MINUTES 15 How long an access token is valid. The app refreshes it automatically.
REFRESH_TOKEN_DAYS 7 How long a sign-in session lasts. After that the user must sign in again.
ENVIRONMENT production development, test, staging or production. In production, the API sends a Strict-Transport-Security header.
Warning

Generate SECRET_KEY with openssl rand -hex 32 and keep it in your secret manager. Changing it later signs everyone out and makes encrypted values, such as MFA seeds, unreadable.

Password rules, lockout and the Require MFA for every user switch are not environment variables. Set them in Password, MFA & SSO → Password policy. See SSO and MFA.

Create the first admin

These settings are read only on the first start, when the database is empty.

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

Set up the database

The bundled PostgreSQL container is configured with:

Setting Default in .env.example What it does
POSTGRES_USER opsnexus Database user.
POSTGRES_PASSWORD none (you must set it) Database password.
POSTGRES_DB opsnexus Database name.

Compose builds DATABASE_URL from these three values. Set them before the first start: the PostgreSQL image creates the user only when its data volume is empty.

Store secrets in Vault

Setting Default in .env.example What it does
SECRET_BACKEND vault vault stores secret values in HashiCorp Vault. local stores them encrypted in PostgreSQL and is for development only.
VAULT_MOUNT secret The KV v2 mount OpsNexus writes to.
VAULT_PREFIX opsnexus Path prefix for OpsNexus secrets inside the mount.

With Docker Compose you do not need anything else. The vault-init service initializes and unseals the bundled Vault, enables KV v2 at secret/, and writes a least-privilege token that the backend reads from a file.

To use your own Vault, you also set VAULT_ADDR and either VAULT_TOKEN or AppRole credentials (VAULT_ROLE_ID and VAULT_SECRET_ID). See Running in production.

Turn on single sign-on

OpsNexus supports sign-in with Google and Microsoft (OpenID Connect). A provider appears on the sign-in page only when both its client ID and secret are set.

Setting What it does
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET OAuth client for Google sign-in.
MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET App registration for Microsoft sign-in.
MICROSOFT_TENANT_ID Your Microsoft Entra tenant ID. Default common.

Register these redirect URIs with the provider, using your PUBLIC_URL:

https://opsnexus.example.com/api/auth/sso/google/callback
https://opsnexus.example.com/api/auth/sso/microsoft/callback
Note

SSO does not create accounts. A person must already exist as a user in OpsNexus, matched by email, before they can sign in with SSO.

See SSO and MFA.

Send email and chat notifications

Email (SMTP), Slack, Microsoft Teams, Google Chat and webhook settings are not environment variables. You add them as notification channels in the app. See Notifications.

Monitor internal addresses

Setting Default What it does
ALLOW_PRIVATE_TARGETS false Lets domain checks and webhooks reach private and internal addresses (10.x, 192.168.x, localhost).
DOMAIN_CHECK_RETENTION_DAYS 30 How long domain check results are kept.
PAGESPEED_API_KEY empty Optional Google PageSpeed Insights API key. Adds Core Web Vitals to SEO reports.
Warning

Keep ALLOW_PRIVATE_TARGETS=false unless you monitor internal services. It protects against server-side request forgery (SSRF).

Tune background jobs

Setting Default What it does
INTEGRATION_SYNC_MINUTES 5 How often pipelines and builds are imported from integrations.
AGENT_OFFLINE_SECONDS 120 How long an agent can be silent before it is marked disconnected.
METRIC_RETENTION_DAYS 30 How long agent metrics are kept.
API_WORKERS 2 Number of API worker processes.
WORKER_CONCURRENCY 4 Number of background jobs one worker container runs at the same time.

Limit browser terminal sessions

Setting Default What it does
TERMINAL_IDLE_MINUTES 30 A browser SSH terminal closes after this many minutes without keyboard input.
TERMINAL_MAX_HOURS 8 Maximum length of a terminal session.
TERMINAL_CONNECT_TIMEOUT_SECONDS 15 How long to wait when connecting to a server.

See Servers and SSH.

Run the bundled build agent

The compose file includes an optional runner service, a build agent in Docker. It uses these settings:

Setting Default What it does
RUNNER_TOKEN empty A registration token (onx_reg_...) created with Create token under Build agents → Download & install.
RUNNER_NAME docker-runner The agent's name.
RUNNER_EXECUTORS 2 How many pipeline runs it takes at the same time.
RUNNER_LABELS linux,docker-runner Labels pipelines use to pick it.

Start it with:

bash
docker compose --profile runner up -d runner

See Build agents.