Environment variables

By setting environment variables for Neptune DXP - Open Edition, you can tailor system behavior such as security controls, session handling, database connections, storage backends, logging, and background processing, without changing application code.

Most environment variables map directly to system settings. If you also configure the same setting through the System Settings tool in the Cockpit, those values take precedence over environment variables. Environment variables are therefore most useful when you need consistent, automated configuration across environments (for example, dev/test/prod), or when you want to enforce baseline defaults that can be overridden via the Cockpit, where appropriate.

Environment variables become relevant in containerized deployments (for example, Docker, Kubernetes), where configuration is typically injected at runtime. In this context, they enable extended configuration checks and controlled manipulation of settings as part of your deployment pipeline, making it easier to validate required values, keep sensitive parameters out of images, and ensure repeatable, environment-specific setups across multiple instances.

Environment variable settings

Each of the following environment variable setting tables is structured to help you quickly understand what you can configure and how each environment variable behaves according to the following data:

Environment variable

The name of the environment variable you can set (including its configuration reference, where applicable).

Type

Indicates what kind of value you can enter (for example, String, Boolean, Array, or a defined set of allowed values).

Default

Shows the default value used when you do not explicitly set the environment variable (where a default is applicable).

Description

Explains what system behavior or setting is affected when the environment variable is configured.

Valid from

Specifies the Neptune DXP - Open Edition version in which the environment variable was first introduced, helping you confirm availability for your deployed version.

Application settings

Use these variables to define the application runtime context (such as environment) and basic instance metadata like name and description.

Application settings table
Environment variable Type Default Description Valid from

DESCRIPTION {description}

String

Installation

The application description

2.0.4

INITIAL_ADMIN_PASSWORD {adminPassword}

String

admin

The initial default password for the admin user

A Neptune DXP - Open Edition instance always starts up with a local admin user. You can set the initial admin password with the environment variable INITIAL_ADMIN_PASSWORD. This value is only used if the underlying database has yet to be initialized. Once the underlying database is initialized, the password is persisted in the underlying database. The value will no longer be valid once the password has been changed in the Neptune DXP - Open Edition Cockpit.

2.0.4

NAME {name}

String

Neptune DXP - Open Edition

The application/instance name

2.0.4

NODE_ENV { env }

production, development, test, build

production

The application environment

In general, use production, development translates into verbose logging.

2.0.4

Node.js settings

As Neptune DXP - Open Edition is written on top of Node.js, you can configure Node.js by setting Node.js CLI environment variables. This can be especially useful when configuring outbound SSL/TLS. The following overview lists a few noteworthy variables. For proper usage, see the official Node.js Documentation.

Node.js settings table
Environment variable Type Default Description Valid from

NODE_EXTRA_CA_CERTS

String

Empty string

When set, the well known "root" CAs (like VeriSign) will be extended with the extra certificates in file.

See Node.js documentation.

NODE_TLS_REJECT_UNAUTHORIZED

String

Empty string

When set to 0, TLS certificate validation is disabled for all TLS connections (and therefore HTTPS too).

See Node.js documentation.

OPENSSL_CONF

String

Empty string

If set, Node.js will load the specified OpenSSL config file at startup.

See Node.js documentation.

SSL_CERT_DIR

String

Empty string

Only takes effect if --use-openssl-ca is enabled. When effective, it overrides OpenSSL’s trusted certificate directory used for CA validation.

See Node.js documentation.

SSL_CERT_FILE

String

Empty string

Only takes effect if --use-openssl-ca is enabled. When effective, it overrides OpenSSL’s trusted certificate directory used for CA validation.

See Node.js documentation.

SSL/TLS settings

Configure HTTPS-related settings, including certificates and keys, to control how the application handles encrypted traffic.

You can enable SSL within the Neptune DXP - Open Edition Cockpit. By default, this is disabled. Set the ENABLE_SSL environment variable to enable SSL and specify other relevant environment variables.

SSL/TLS settings table
Environment variable Type Default Description Valid from

ENABLE_SSL {enableSSL}

Boolean

false

Run Neptune DXP - Open Edition in HTTPS mode

2.0.4

SSLCA {sslCa}

String

Empty string

The SSL certificate authority

Required if SSL enabled and an SSL Certificate Authority is issued.

2.0.4

SSLCERT {sslCert}

String

Empty string

The SSL certificate

Required if SSL enabled.

2.0.4

SSLKEY {sslKey}

String

Empty string

The SSL private key (sensitive)

Required if SSL enabled.

2.0.4

SSLPASSPHRASE {sslPassphrase}

String

Empty string

The SSL passphrase

Required if SSL enabled and a passphrase is required

2.0.4

Session and authentication settings

Adjust session behavior and sign-in/sign-out handling, including cookie settings and logout propagation to external identity systems.

Session and authentication settings table
Environment variable Type Default Description Valid from

LOGOUT_COCKPIT_EXTERNAL {logoutCockpitExternal}

Boolean

false

Signout from the Cockpit causes signout from external systems (Microsoft Entra ID, OpenID Connect, SAML)

24.10.0

LOGOUT_LAUNCHPAD_EXTERNAL {logoutLaunchpadExternal}

Boolean

true

Signout from the launchpad causes signout from external systems (Microsoft Entra ID, OpenID Connect, SAML)

24.10.0

OE_SESSION_COOKIE_NAME {sessionCookieName}

String

oe_session

Name of the session cookie issued by Neptune DXP - Open Edition.

24.10.0

SESSION_COOKIE {sessionCookie}

Boolean

false

When set, no expiry is set on the cookie. Cookie will be removed when all browser windows are closed.

22.10.0

SESSION_SECRET {sessionSecret}

String

Empty string

Secret used to sign session cookies. If not set, a random secret is generated on first use.

24.14.1

SESSION_TIMEOUT {sessionTimeout}

Natural number

180

User session timeout in minutes

2.0.4

Server settings

Control core runtime server behavior such as instance scaling, networking, and internal host resolution.

Server settings table
Environment variable Type Default Description Valid from

INSTANCES {instances}

Natural number

2

The number of child processes with which Neptune DXP - Open Edition should start up

2.0.4

PLANET9_IP {ip}

IP address

::

The IP to listen on (not mandatory)

21.10.2

PLANET9_LOCAL_HOST_NAME {localHostName}

String

localhost

The hostname Neptune DXP - Open Edition uses to call itself

22.10.7

PORT {port}

Port

8080

The port to bind

2.0.4

SSL_PORT {sslPort}

Port

8081

The SSL port to bind

Required if SSL enabled.

24.0.0

Timeout settings

Tune request timeouts to control how long the system waits before failing slow responses or external calls.

Timeout settings table
Environment variable Type Default Description Valid from

CLIENT_REQUEST_TIMEOUT {clientRequestTimeout}

Natural number

120

Client request timeout (from client to external API endpoints) in seconds. Minimum 5 seconds.

21.10.2

HTTP_RESPONSE_TIMEOUT {httpResponseTimeout}

Natural number

120

HTTP response timeout (from Neptune DXP - Open Edition to the client) in seconds

2.6.0

Payload size limits

Set maximum allowed payload sizes to protect the system from oversized requests and to align with your integration requirements.

Payload size limits settings table
Environment variable Type Default Description Valid from

MAX_JSON_PAYLOAD_SIZE {payloads.json}

Natural number

100

Maximum size (in MB) for JSON payloads

23.10.7

MAX_PLAIN_TEXT_PAYLOAD_SIZE {payloads.text}

Natural number

100

Maximum size (in MB) for plain text payloads

23.10.7

MAX_URL_ENCODED_PAYLOAD_SIZE {payloads.url}

Natural number

100

Maximum size (in MB) for URL-encoded payloads

23.10.7

Server scripts

Configure how server scripts behave at runtime, including logging and restricting visibility of sensitive environment variables.

Server scripts settings table
Environment variable Type Default Description Valid from

SCRIPT_HIDDEN_ENV {serverScriptHiddenEnv}

String

Empty string

Comma-separated list of environment variable names to hide from server scripts

24.14.1

SCRIPT_LOG_STDOUT {serverScriptLogToStdout}

Boolean

false

If true, logging in server scripts is sent to stdout

22.10.10

Security settings

Reinforce the system with security-focused controls such as CSP behavior, framing protection, and account lock messaging.

Security settings table
Environment variable Type Default Description Valid from

ALLOW_ORIGIN_WHITELIST {security.allowOrigin}

Array

[]

The domains allowed to access Neptune DXP - Open Edition

21.10.2

CSP_WHITELIST {security.contentSecurityPolicy}

Array

[]

The domains allowed to be loaded by Neptune DXP - Open Edition

21.10.2

DISABLE_FRAME_GUARD {security.disableFrameGuard}

Boolean

false

Removes X-Frame-Options from response headers

21.10.2

ENABLE_STRICT_CSP {security.enableStrictCSP}

Boolean

false

Enables a strict Content Security Policy

24.14.0

SAMESITE_VALUE {security.sameSiteValue}

None, Strict, Lax

Strict

SameSite attribute value for cookie

21.10.2

SEND_NOTIFICATION_ON_LOCKED_ACCOUNT {passwordLock.sendNotificationOnLockedAccount}

Boolean

true

Send notification email when account is locked due to too many login attempts

24.11.0

USE_NEUTRAL_LOCKED_ACCOUNT_MESSAGE {passwordLock.showNeutralLockedMessage}

Boolean

false

Show a neutral error message when a locked account is accessed

24.11.0

Proxy settings

Define which destinations can be reached through the proxy and how proxy connections are handled.

Proxy settings table
Environment variable Type Default Description Valid from

PROXY_KEEP_ALIVE {proxy.keepAlive}

Boolean

false

Enable persistent (keep-alive) connections when proxying requests

23.10.10

PROXY_RESTRICTED_ENABLED {proxy.restrictedEnabled}

Boolean

false

Only allow API, OData, or remote system endpoints when sending requests through the proxy

23.10.6

PROXY_SSL_KEEP_ALIVE {proxy.sslKeepAlive}

Boolean

false

Enable persistent (keep-alive) SSL connections when proxying requests through the proxy

23.10.10

PROXY_WHITELIST {proxy.whitelist}

Array

[]

The domains allowed to proxy

21.10.2

HTTPS hosting

Specify whether the application is hosted behind HTTPS (for example via a reverse proxy), impacting security behavior and URL handling.

HTTPS hosting settings table
Environment variable Type Default Description Valid from

HTTPS_HOSTED {https.hosted}

Boolean

false

Whether Neptune DXP - Open Edition is accessed over HTTPS or not

This does not mean that Neptune DXP - Open Edition runs in HTTPS mode. nginx, haproxy, etc. could be handling HTTPS.

21.10.2

Database settings

Neptune DXP - Open Edition persists all its state (apps, server Scripts, APIs, etc.) and the majority of its configuration in an underlying database. By default, a Neptune DXP - Open Edition instance initializes (or connects to) an SQLite database.

The SQLite database is initialized within the container. This means that the SQLite database is ephemeral and is deleted on termination of the container. At the time of writing, mounting volume for the SQLite database is not supported, but this support is in the feature pipeline.

SQLite is only intended for sandbox environments.

General

Select the database type used by the system and define global database behavior.

General database settings table
Environment variable Type Default Description Valid from

DB_TYPE {dbType}

mongo, postgresql, mysql, sqlite, mssql

sqlite

The type of database running

2.0.4

MongoDB

Provide MongoDB connection configuration where MongoDB is used as the database back end.

MongoDB settings table
Environment variable Type Default Description Valid from

DB_URI_MONGODB {dbTypes.mongo.uri}

String

N/A

The URI for the database. If set, other options are ignored.

2.1.0

MSSQL

Define connection and pool settings for Microsoft SQL Server environments.

The target database must have a schema named planet9 (unless configured otherwise) before connecting a Neptune DXP - Open Edition instance to it. If the database is empty, Neptune DXP - Open Edition initializes all required tables and data on startup.

MSSQL settings table
Environment variable Type Default Description Valid from

DB_MSSQL_DBNAME {dbTypes.mssql.database}

String

planet9

The name of the database

2.1.0

DB_MSSQL_HOST {dbTypes.mssql.host}

String

localhost

Database host name/IP

2.1.0

DB_MSSQL_PASSWORD {dbTypes.mssql.password}

String

N/A

The password for the database user (sensitive)

2.1.0

DB_MSSQL_POOL_SIZE_MAX {dbTypes.mssql.poolSizeMax}

Natural number

10

The maximum number of connections there can be in the pool

21

DB_MSSQL_POOL_SIZE_MIN {dbTypes.mssql.poolSizeMin}

Natural number

0

The minimum of connections there can be in the pool

21

DB_MSSQL_PORT {dbTypes.mssql.port}

Port

1433

Database port

2.1.0

DB_MSSQL_REQUEST_TIMEOUT {dbTypes.mssql.requestTimeout}

Natural number

60

Request timeout in seconds

21.10.2

DB_MSSQL_SCHEMA {dbTypes.mssql.schema}

String

planet9

The database schema name

2.1.0

DB_MSSQL_USER {dbTypes.mssql.username}

String

-

The username for the database

2.1.0

PostgreSQL

Provide connection details and tuning options for PostgreSQL deployments.

You can configure your connection string with a single environment variable, using DB_URI_POSTGRES or you can configure each part of a connection with individual variables.

The target database must have a schema named planet9 before connecting a Neptune DXP - Open Edition instance to it. If the database is empty, Neptune DXP - Open Edition initializes all required tables and data on startup.

PostgreSQL settings table
Environment variable Type Default Description Valid from

DB_PSQL_DBNAME {dbTypes.postgresql.database}

String

Planet9

The database name

2.0.4

DB_PSQL_HOST {dbTypes.postgresql.host}

String

localhost

Database host name/IP

2.0.4

DB_PSQL_PASSWORD {dbTypes.postgresql.password}

String

Empty string

The password for the database user (sensitive)

2.0.4

DB_PSQL_POOL_SIZE {dbTypes.postgresql.poolsize}

Natural number

10

The pool size of the database connector

22.10.15

DB_PSQL_PORT {dbTypes.postgresql.port}

Port

5432

Database port

2.0.4

DB_PSQL_QUERY_TIMEOUT {dbTypes.postgresql.queryTimeout}

Natural number

60

The query timeout in seconds

23.10.11

DB_PSQL_SCHEMA {dbTypes.postgresql.schema}

String

planet9

Database schema

24.11.0

DB_PSQL_SSL {dbTypes.postgresql.ssl}

Boolean

false

Enable SSL mode for the database

2.0.4

DB_PSQL_USER {dbTypes.postgresql.user}

String

Empty string

The username for the database

2.0.4

DB_URI_POSTGRES {dbTypes.postgresql.uri}

String

-

The URI for the database. If set, other options are ignored.

2.0.4

Redis (In-Memory Database)

Enable Redis-backed in-memory storage and configure the Redis connection URI.

Redis settings table
Environment variable Type Default Description Valid from

DB_ENABLED_REDIS {inmemorydb.enabled}

Boolean

true

Use redis in-memory database

22.10.0

DB_URI_REDIS {inmemorydb.uri}

String

Empty string

The URI for the database

22.10.0

SQLite

Configure file paths for SQLite databases used for core data and custom entities.

SQLite settings table
Environment variable Type Default Description Valid from

DB_SQLITE_ENTITIES_PATH {dbTypes.sqlite.databaseEntities}

String

./db/planet9-entities.sqlite

Path for the SQLite database with all the entities data

2.1.0

DB_SQLITE_PATH {dbTypes.sqlite.database}

String

./db/planet9.sqlite

Path for the SQLite database with which the Neptune DXP - Open Edition instance will initialize (or connect).

2.1.0

Storage settings

GOS (Global Object Storage)

Configure storage for global objects and shared items, including optional cloud-backed storage settings.

GOS settings table
Environment variable Type Default Description Valid from

STORAGE_GOS_AZURE_ACCOUNT_KEY {storage.gos.azure.accountKey}

String

Empty string

Account key

23.10.2

STORAGE_GOS_AZURE_ACCOUNT_NAME {storage.gos.azure.accountName}

String

Empty string

Name of the Azure account

23.10.2

STORAGE_GOS_AZURE_CONTAINER {storage.gos.azure.container}

String

Empty string

Container name

23.10.2

STORAGE_GOS_FILE_PATH {storage.gos.file.path}

String

Empty string

Folder path to store GOS items

23.10.2

STORAGE_GOS_TYPE {storage.gos.type}

DB, AZURE, FILE

DB

The type of storage to be used for GOS

23.10.2

Media storage

Choose where Media Library files are stored (database, file system, or cloud storage) and configure the required connection details.

Media storage settings table
Environment variable Type Default Description Valid from

STORAGE_MEDIA_AZURE_ACCOUNT_KEY {storage.media.azure.accountKey}

String

Empty string

Account key

23.10.0

STORAGE_MEDIA_AZURE_ACCOUNT_NAME {storage.media.azure.accountName}

String

Empty string

Name of the Azure account

23.10.0

STORAGE_MEDIA_AZURE_CONTAINER {storage.media.azure.container}

String

Empty string

Container name

23.10.0

STORAGE_MEDIA_FILE_PATH {storage.media.file.path}

String

Empty string

Folder path to store media files

23.10.0

STORAGE_MEDIA_TYPE {storage.media.type}

DB, AZURE, FILE

DB

The type of storage to be used for the Media Library

23.10.0

Mobile storage

Configure storage for generated mobile builds, including cloud or file-based storage targets.

Mobile storage settings table
Environment variable Type Default Description Valid from

STORAGE_MOBILE_AZURE_ACCOUNT_KEY {storage.mobile.azure.accountKey}

String

Empty string

Account key

23.10.0

STORAGE_MOBILE_AZURE_ACCOUNT_NAME {storage.mobile.azure.accountName}

String

Empty string

Name of the Azure account

23.10.0

STORAGE_MOBILE_AZURE_CONTAINER {storage.mobile.azure.container}

String

Empty string

Container name

23.10.0

STORAGE_MOBILE_FILE_PATH {storage.mobile.file.path}

String

Empty string

Folder path to store mobile builds

23.10.0

STORAGE_MOBILE_TYPE {storage.mobile.type}

DB, AZURE, FILE

DB

The type of storage to be used for mobile builds

23.10.0

PDF storage

Control where generated PDFs are stored and how the storage back end is accessed.

PDF storage settings table
Environment variable Type Default Description Valid from

STORAGE_PDF_AZURE_ACCOUNT_KEY {storage.pdf.azure.accountKey}

String

Empty string

Account key

23.10.0

STORAGE_PDF_AZURE_ACCOUNT_NAME {storage.pdf.azure.accountName}

String

Empty string

Name of the Azure account

23.10.0

STORAGE_PDF_AZURE_CONTAINER {storage.pdf.azure.container}

String

Empty string

Container name

23.10.0

STORAGE_PDF_FILE_PATH {storage.pdf.file.path}

String

Empty string

Folder path to store PDFs

23.10.0

STORAGE_PDF_TYPE {storage.pdf.type}

DB, AZURE, FILE

DB

The type of storage to be used for PDFs

23.10.0

Background jobs

Control how frequently background processing runs, which affects scheduled tasks and asynchronous workloads.

Background jobs settings table
Environment variable Type Default Description Valid from

BACKGROUNDJOB_INTERVAL {backgroundJobs.interval}

Natural number

60

How often the engine should check to see if there are any jobs to run (in seconds)

2.0.4

Monitoring and logging

Configure logging behavior and operational telemetry to support diagnostics, auditing, and observability.

Monitoring and logging settings table
Environment variable Type Default Description Valid from

DISABLE_AUDIT_LOG {disableAuditLog}

Boolean

false

Disable audit log

22.10.4

DISABLE_TELEMETRY {disableTelemetry}

Boolean

false

If true, disables telemetry data collection

24.12.1

P9_LOG_REQUESTS {log.requests}

Boolean

false

Log all requests to stdout and the requests folder

21.10.2

Prometheus metrics

Enable and expose Prometheus metrics endpoints to integrate with monitoring and alerting systems.

Prometheus metrics settings table
Environment variable Type Default Description Valid from

P9_PROMETHEUS_ENABLED {prometheus.enabled}

Boolean

false

Log all requests in the Prometheus format

24.11.0

P9_PROMETHEUS_EXPOSE_METRICS {prometheus.exposeMetrics}

Boolean

false

Expose the /metrics endpoint on the main application

24.11.0

P9_PROMETHEUS_PORT {prometheus.port}

Number

8999

The port the main Prometheus process listens to

24.11.0

Development and package settings

Apply development-time safeguards and enforcement rules for development packages, artifacts, and database updates.

Development and package settings table
Environment variable Type Default Description Valid from

REQUIRE_PACKAGE {requirePackage}

Boolean

false

Require development package for all artifacts

24.11.0

REQUIRE_TABLE_ROLE {requireTableRole}

Boolean

false

Require role for all tables

24.14.0

RESTRICT_DATABASE_UPDATE_FROM_REPO {restrictDatabaseUpdateFromRepo}

Boolean

false

Restricts the update database from repository on development packages

24.10.0

SKIP_PACKAGE_IMPORT {skipInternalPackageImport}

Boolean

false

Do not import internal development package data on startup

24.11.0

AI Integration

Configure API keys and integration settings used by AI-enabled functionality.

AI integration settings table
Environment variable Type Default Description Valid from

DXP_EXA_API_KEY {exa.privateApiKey}

String

Empty string

Exa API for WebSearch (sensitive)

24.14.0

Cloud and tenant settings

Define cloud tenant identifiers and environment-specific cloud configuration values.

Cloud and tenant settings table
Environment variable Type Default Description Valid from

DXPCLOUD_TENANT_UUID {tenantUuid}

String

Empty string

Tenant UUID on Neptune DXP Cloud

24.12.0

Configuration management

Control whether configuration changes can be persisted and which sensitive config paths should be excluded from saved configuration.

Configuration management settings table
Environment variable Type Default Description Valid from

CONFIG_LOCKED

Boolean

false

When set to 1, true, yes, y, or on, prevents configuration changes in the System Settings tool from being saved

24.14.0

CONFIG_SECRETS

String

undefined

Hide config parameters from file and database that can be set with environment variables. Accepts a comma-delimited list of parameters, for example adminPassword,dbTypes.postgresql.password

22.10.0

Related topics