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. If an environment variable was introduced in a patch release of this version, the description states the patch version it is available from.
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 | ||
|---|---|---|---|---|---|
|
String |
|
The application description |
||
|
String |
|
The initial default password for the
|
||
|
String |
|
The application/instance name |
||
|
|
|
Defines the application runtime environment.
|
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 |
|---|---|---|---|
|
String |
Empty string |
When set, the well known "root" CAs (like VeriSign) will be extended with the
extra certificates in |
|
String |
Empty string |
When set to |
|
String |
Empty string |
If set, Node.js will load the specified OpenSSL config file at startup. |
|
String |
Empty string |
Only takes effect if |
|
String |
Empty string |
Only takes effect if |
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 | ||
|---|---|---|---|---|---|
|
Boolean |
|
Run Neptune DXP - Open Edition in HTTPS mode |
||
|
String |
Empty string |
The SSL certificate authority
|
||
|
String |
Empty string |
The SSL certificate
|
||
|
String |
Empty string |
The SSL private key (sensitive)
|
||
|
String |
Empty string |
The SSL passphrase
|
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 | ||
|---|---|---|---|---|---|
|
Boolean |
|
Signout from the Cockpit causes signout from external systems (Microsoft Entra ID, OpenID Connect, SAML) |
||
|
Boolean |
|
Signout from the launchpad causes signout from external systems (Microsoft Entra ID, OpenID Connect, SAML) |
||
|
String |
|
Name of the session cookie issued by Neptune DXP - Open Edition. |
||
|
Boolean |
|
When set, no expiry is set on the cookie. Cookie will be removed when all browser windows are closed.
|
||
|
String |
Empty string |
Secret used to sign session cookies. If not set, a random secret is generated on first use. Set this in multi-instance setups. Available from version 24.14.1. |
||
|
Boolean |
|
Stores sessions in Redis instead of the Available from version 24.14.5.
|
||
|
Natural number |
|
User session timeout in minutes |
Server settings
Control core runtime server behavior such as instance scaling, networking, and internal host resolution.
Server settings table
| Environment variable | Type | Default | Description | ||
|---|---|---|---|---|---|
|
Natural number |
|
Time in seconds that a query result cached without a cache group is kept. Nothing clears it earlier. Available from version 24.14.5. |
||
|
Boolean |
|
Keeps query results, the launchpad structure and tile images in the memory of each process for a short time. Set to Cached data such as the global admin roles and ACL lists is kept for one minute per web worker. A change made on one web worker can therefore take up to one minute to reach the others. Available from version 24.14.5. |
||
|
Natural number |
|
Time in hours that a cached query result or launchpad structure is kept if no write to its tables clears it earlier Available from version 24.14.5. |
||
|
Natural number |
|
Number of query results each process keeps before the oldest are evicted Available from version 24.14.5. |
||
|
Natural number |
|
Maximum size in MB of a single query result. Larger results are not cached. Available from version 24.14.5. |
||
|
Natural number |
|
Size in MB of the query results each process keeps before the oldest are evicted Available from version 24.14.5. |
||
|
Natural number |
|
The number of child processes with which Neptune DXP - Open Edition should start up |
||
|
Natural number |
|
Grace period in seconds for a graceful shutdown |
||
|
IP address |
|
The IP to listen on (not mandatory) |
||
|
String |
|
The hostname Neptune DXP - Open Edition uses to call itself |
||
|
Port |
|
The port to bind |
||
|
Port |
|
The SSL port to bind
|
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 |
|---|---|---|---|
|
Natural number |
|
Client request timeout (from client to external API endpoints) in seconds. Minimum 5 seconds. |
|
Natural number |
|
HTTP response timeout (from Neptune DXP - Open Edition to the client) in seconds |
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 |
|---|---|---|---|
|
Natural number |
|
Maximum size (in MB) for JSON payloads |
|
Natural number |
|
Maximum size (in MB) for plain text payloads |
|
Natural number |
|
Maximum size (in MB) for URL-encoded payloads |
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 |
|---|---|---|---|
|
|
Empty string |
When set to Available from version 24.14.5. |
|
String |
|
Path to the folder where custom npm modules for server scripts are located and installed |
|
|
|
The log level of server scripts. Overrides |
|
String |
Empty string |
Comma-separated list of environment variable names to hide from server scripts Available from version 24.14.1. |
|
Boolean |
|
If |
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 |
|---|---|---|---|
|
Array |
|
The domains allowed to access Neptune DXP - Open Edition |
|
Array |
|
The domains allowed to be loaded by Neptune DXP - Open Edition |
|
Boolean |
|
Removes |
|
Boolean |
|
Enables a strict Content Security Policy |
|
|
|
|
|
Boolean |
|
Send notification email when account is locked due to too many login attempts |
|
Boolean |
|
Show a neutral error message when a locked account is accessed |
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 |
|---|---|---|---|
|
Boolean |
|
Enable persistent (keep-alive) connections when proxying requests |
|
Boolean |
|
Only allow API, OData, or remote system endpoints when sending requests through the proxy |
|
Boolean |
|
Enable persistent (keep-alive) SSL connections when proxying requests through the proxy |
|
Array |
|
The domains allowed to proxy |
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 | ||
|---|---|---|---|---|---|
|
Boolean |
|
Whether Neptune DXP - Open Edition is accessed over HTTPS or not
|
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. Neptune DXP -
Open Edition supports Microsoft SQL Server, PostgreSQL, and SQLite, selected
through the DB_TYPE environment variable. 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 a volume for the SQLite database is not supported, but this support is in the feature pipeline.
| SQLite is intended only for sandbox environments. For a production setup, use Microsoft SQL Server or PostgreSQL. |
General
Select the database type used by the system and define global database behavior.
General database settings table
| Environment variable | Type | Default | Description |
|---|---|---|---|
|
|
|
The type of database running |
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 |
|---|---|---|---|
|
String |
|
The name of the database |
|
Natural number |
|
Time in seconds that jobs and scripts in a script executor wait for a database connection before they fail Available from version 24.14.5. |
|
String |
|
Database host name, FQDN or IP |
|
String |
Empty string |
The password for the database user (sensitive) |
|
Natural number |
|
Time in seconds that a request waits for a database connection. If no connection is available in time, the request fails with HTTP status 503. Available from version 24.14.5. |
|
Natural number |
|
The maximum number of connections there can be in the pool |
|
Natural number |
|
The minimum of connections there can be in the pool |
|
Port |
|
Database port |
|
Natural number |
|
Request timeout in seconds |
|
String |
|
The database schema name |
|
String |
Empty string |
The username for the database |
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 |
|---|---|---|---|
|
String |
|
The database name. The name is case-sensitive. |
|
Natural number |
|
Time in seconds that jobs and scripts in a script executor wait for a database connection before they fail Available from version 24.14.5. |
|
String |
|
Database host name/IP |
|
String |
Empty string |
The password for the database user (sensitive) |
|
Natural number |
|
Time in seconds that a request waits for a database connection. If no connection is available in time, the request fails with HTTP status 503. Available from version 24.14.5. |
|
Natural number |
|
The pool size of the database connector |
|
Port |
|
Database port |
|
Natural number |
|
The query timeout in seconds |
|
String |
|
Database schema |
|
Boolean |
|
Enable SSL mode for the database |
|
String |
Empty string |
The username for the database |
|
String |
Empty string |
The URI for the database. If set, other options are ignored. |
Redis (In-Memory Database)
Enable Redis-backed in-memory storage and configure the Redis connection URI.
Redis settings table
| Environment variable | Type | Default | Description |
|---|---|---|---|
|
Boolean |
|
Use the Redis in-memory database. |
|
String |
Empty string |
The URI for the database |
SQLite
Configure file paths for SQLite databases used for core data and custom entities.
SQLite settings table
| Environment variable | Type | Default | Description |
|---|---|---|---|
|
String |
|
Path for the SQLite database with all the entities data |
|
String |
|
Path for the SQLite database with which the Neptune DXP - Open Edition instance will initialize (or connect). |
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 |
|---|---|---|---|
|
String |
Empty string |
Account key |
|
String |
Empty string |
Name of the Azure account |
|
String |
Empty string |
Container name |
|
String |
Empty string |
Folder path to store GOS items |
|
|
|
The type of storage to be used for GOS |
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 |
|---|---|---|---|
|
String |
Empty string |
Account key |
|
String |
Empty string |
Name of the Azure account |
|
String |
Empty string |
Container name |
|
String |
Empty string |
Folder path to store media files |
|
|
|
The type of storage to be used for the Media Library |
Mobile storage
Configure storage for generated mobile builds, including cloud or file-based storage targets.
Mobile storage settings table
| Environment variable | Type | Default | Description |
|---|---|---|---|
|
String |
Empty string |
Account key |
|
String |
Empty string |
Name of the Azure account |
|
String |
Empty string |
Container name |
|
String |
Empty string |
Folder path to store mobile builds |
|
|
|
The type of storage to be used for mobile builds |
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 |
|---|---|---|---|
|
String |
Empty string |
Account key |
|
String |
Empty string |
Name of the Azure account |
|
String |
Empty string |
Container name |
|
String |
Empty string |
Folder path to store PDFs |
|
|
|
The type of storage to be used for PDFs |
Background jobs
Control how frequently background processing runs, which affects scheduled tasks and asynchronous workloads.
Background jobs settings table
| Environment variable | Type | Default | Description |
|---|---|---|---|
|
Natural number |
|
How often the engine should check to see if there are any jobs to run (in seconds) |
|
|
|
When set to |
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 |
|---|---|---|---|
|
Boolean |
|
Disable audit logging for artifact create, save and delete |
|
Boolean |
|
If |
|
String |
|
Folder path to store the log files |
|
Boolean |
|
Log all requests to |
|
String |
|
Maximum size of a log file, after which the file rotates. Enter a number directly followed by the unit |
|
|
|
Sets the log level limit of the server. Also applies to server scripts, unless |
Prometheus metrics
Enable and expose Prometheus metrics endpoints to integrate with monitoring and alerting systems.
Prometheus metrics settings table
| Environment variable | Type | Default | Description |
|---|---|---|---|
|
Boolean |
|
Log all requests in the Prometheus format |
|
Boolean |
|
Expose the |
|
Number |
|
The port the main Prometheus process listens to |
When P9_PROMETHEUS_ENABLED is true, every web worker exposes the following
metrics through the cluster metrics endpoint. You can use them to scrape the
database pool usage of all web workers across instances.
Available from version 24.14.5.
p9_db_pool_connections-
The number of database pool connections, labelled by
pidandstate. p9_query_cache_bytes-
The memory used by the query cache, in bytes.
p9_query_cache_entries-
The number of entries in the query cache.
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 |
|---|---|---|---|
|
Boolean |
|
Always minifies the source code of applications. Only the value |
|
Boolean |
|
Require development package for all artifacts |
|
Boolean |
|
Require role for all tables |
|
Boolean |
|
Restricts the update database from repository on development packages |
|
Boolean |
|
Do not import internal development package data on startup |
AI Integration
Configure API keys and integration settings used by AI-enabled functionality.
AI integration settings table
| Environment variable | Type | Default | Description |
|---|---|---|---|
|
String |
Empty string |
Exa API for WebSearch (sensitive) |
Cloud and tenant settings
Define cloud tenant identifiers and environment-specific cloud configuration values.
Cloud and tenant settings table
| Environment variable | Type | Default | Description |
|---|---|---|---|
|
String |
Empty string |
Tenant UUID on Neptune DXP Cloud |
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 |
|---|---|---|---|
|
Boolean |
|
When set to |
|
String |
|
Hide config parameters from file and database that can be set with environment
variables. Accepts a comma-delimited list of parameters, for example |