Configuration reference

Everything is configured with environment variables. Docker Compose reads them from .env (start from .env.example). The Helm chart sets them from its values (helm/values.yaml); the names below are the variable names, which is also what an existingSecret or extraEnv uses.

Most installations set fewer than ten of these. The rest have defaults that suit a normal site.

#Required

Variable	Meaning
`APP_SECRET`	The key that encrypts credentials stored in the database (git tokens, integration configurations, the private Maven repository password). 64 hex characters (`openssl rand -hex 32`). The backend will not start in production without it. Do not just change it: stored credentials would become unreadable. Replace it with the rotation tool (Running dpndncY). It does not sign sessions or API tokens; that is a separate key that rotates by itself (below)
`CORS_ORIGIN`	The origin browsers use, for example `https://dpndncy.example.com`. The backend will not start in production without it. Several origins can be given comma separated; `*` is refused. Compose and Helm derive it from `DOMAIN` / `config.publicUrl`
`SUPERADMIN_EMAIL`, `SUPERADMIN_PASSWORD`	The first operator account. Used while `ENABLE_BOOTSTRAP_SUPERADMIN=true`

#Addresses

Variable	Default	Meaning
`DOMAIN`, `API_DOMAIN`		Compose only. The console and API hostnames
`NEXT_PUBLIC_APP_ORIGIN`	`http://localhost:3000`	The origin the console presents to the API on its own requests. Must be one of `CORS_ORIGIN`. Set it to the console address
`APP_URL`	`http://localhost:3000`	The console address, used in links in emails and exports
`PUBLIC_API_URL`	`APP_URL`	The API address shown in generated pipeline snippets and agent instructions. Set it when the API has its own hostname
`PORT`	`3001`	The API port inside the container
`WEB_PORT`	`3000`	The console port inside the container
`TRUST_PROXY`	off	`true` trusts one reverse-proxy hop for the client address (needed behind Caddy, nginx or an ingress, otherwise every visitor shares one rate-limit bucket). Any other value is passed to Express as its `trust proxy` setting

Variable	Default	Meaning
`ENABLE_BOOTSTRAP_SUPERADMIN`	`false`	Creates or updates the operator account from `SUPERADMIN_*` at every start. While true, a restart resets that account's password. Turn it off after your first sign-in
`SUPERADMIN_NAME`	`Superadmin`	Display name
`COOKIE_SECURE`	`true`	Send the session cookie only over HTTPS. Set `false` only for plain-HTTP evaluation
`COOKIE_DOMAIN`		Cookie domain, if the console and another host must share it
`SESSION_TTL_SECONDS`	`28800`	Browser session length (8 hours). Sessions also end whenever the server restarts
`MFA_TTL_SECONDS`	`300`	How long the second step of sign-in stays valid
`SERVICE_TOKEN_TTL_SECONDS`	`2592000`	Lifetime of internal service tokens
`AUTH_RATE_LIMIT`	`20`	Sign-in attempts per 15 minutes per address
`API_RATE_LIMIT`	`300`	API requests per minute per address
`OIDC_ISSUER_URL`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, `OIDC_REDIRECT_URI`, `OIDC_SCOPES`		Single sign-on with OpenID Connect. Register `https://<console>/api/auth/oidc/callback`
`SAML_IDP_SSO_URL`, `SAML_IDP_CERT`, `SAML_SP_ENTITY_ID`, `SAML_SP_ACS_URL`		SAML 2.0. The service provider metadata is at `/api/auth/saml/metadata`

API tokens created in Settings do not expire with a restart. They are valid for 365 days unless you choose otherwise when creating them, and each user can hold up to 10.

#Outbound proxy

Variable	Meaning
`HTTPS_PROXY`, `HTTP_PROXY`	The proxy for outbound connections (advisory lookups, registries, integrations)
`NO_PROXY`	Destinations that bypass it. The container always adds `127.0.0.1`, `localhost` and `::1` itself

When a proxy variable is present the container switches on Node's proxy support at start-up; nothing else is needed. The proxy must allow the destinations in Ports and networking, and the machine must trust the proxy's certificate authority if it re-signs TLS.

#Key rotation

Variable	Default	Meaning
`JWT_SECRET_ROTATION_DAYS`	`0` (off); `90` in `.env.example` and the Helm chart	Rotates the key that signs sessions and API tokens when it is this many days old. Nobody is signed out: the previous key keeps verifying until its window ends
`JWT_SECRET_VERIFY_WINDOW_DAYS`	`400`	How long a retired signing key keeps verifying tokens. It must be at least as long as the longest API token, or those tokens stop working after a rotation
`API_TOKEN_MAX_DAYS`	`0` (no cap)	The longest an API token may live. Longer requests, and "never expires", are cut to this. Setting it forces pipelines to replace their tokens on a schedule; 90 to 365 is typical

If rotation is on and the verify window is shorter than the longest possible token, the server says so in its log at start-up.

#Storage

Variable	Default	Meaning
`DB_PATH`	`./data/dpndncY.db`	The SQLite database. In the container this is inside `/app/data`, which must be a persistent volume

There is no external database option. dpndncY runs on SQLite, one container per installation.

#Email

Variable	Default	Meaning
`SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`, `SMTP_FROM`		Outgoing mail for invitations, alerts and scheduled reports. Without it no email is sent: when you create a tenant owner or a user, set their initial password yourself

#Vulnerability data

Variable	Default	Meaning
`NVD_API_KEY`		Raises NVD rate limits. Free from nvd.nist.gov
`GITHUB_TOKEN`		Adds GitHub advisory data and raises GitHub rate limits
`GHSA_ENABLED`	`true`	Use GitHub security advisories
`OSV_TIMEOUT_MS`, `OSV_MAX_RETRIES`	`15000`, `3`	OSV.dev request behaviour
`DPNDNCY_AIRGAPPED`	`false`	No outbound calls. Vulnerability data comes from an imported offline database (Running dpndncY without internet access (air-gapped))

OSV.dev is always used and needs no key.

#Limits

Variable	Default	Meaning
`MAX_ZIP_UPLOAD_MB`	`200`	Largest source archive the API accepts
`MAX_ZIP_FILES`	`4000`	Most files read from one archive
`JSON_LIMIT`	`2mb`	Largest JSON request body
`CLI_TIMEOUT_MS`	`120000`	Time allowed for tool calls made while scanning
`MAVEN_TIMEOUT_MS`	`300000`	Time allowed for a Maven resolution
`MONITORING_WORKER_INTERVAL_MS`	`300000`	How often the continuous-monitoring worker looks for projects due for a rescan
`ALLOWED_PROJECT_PATHS`		Folders on the server, in addition to the workspaces created by uploads, that may be scanned by path (comma separated). Empty by default. Pipelines upload source, so they do not need this

#Licence

Variable	Default	Meaning
`LICENSE_SERVER_URL`	`https://license.dpndncy.com`	Used by Settings, License, Activate online
`DPNDNCY_LICENSE_HEARTBEAT`	`false`	Opt-in daily check-in carrying the licence id and aggregate counts only. Always off when air-gapped

A new installation runs a 30-day trial. After it ends, or when a licence expires and its 7-day grace period ends, the installation turns read-only: data stays visible and new scans are blocked.

#Optional hardening

Variable	Meaning
`DPNDNCY_NODE_WORKER_IMAGE`, `DPNDNCY_PYTHON_WORKER_IMAGE`, `DPNDNCY_MAVEN_WORKER_IMAGE`	Container images used to run untrusted package or build steps in isolation. When unset, those steps are not run
`ALLOWED_PRIVATE_REGISTRIES`	Private HTTPS container registries (host or host:port) that image scans may reach. Private addresses are refused by default
`SAST_EXTERNAL_AI_ENABLED`	`false`. When true, rule metadata (never source code) may be sent to an external service for guidance

#A note on `.env` files

On a machine where the application starts from a folder containing a .env file, that file overrides variables set in the process environment. The container image contains no .env file, so there the environment you pass is what applies. If a setting appears to be ignored on a bare-metal install, check for a .env in the working directory.

← Previous

Handing it to a customer

Backups, upgrades, rotation