Environment variables

View as Markdown

This section lists all environment variables that Krenalis reads at startup. Krenalis will also attempt to load variables from the .env file, if present.

Database

Settings used to access the PostgreSQL server used by Krenalis.

Variable Description
KRENALIS_DB_HOST Address of the PostgreSQL server. Example: localhost.
Default: 127.0.0.1
KRENALIS_DB_PORT Port number used by PostgreSQL.
Default: 5432
KRENALIS_DB_USERNAME PostgreSQL username.
KRENALIS_DB_PASSWORD PostgreSQL password. In testing environments or other contexts where the server does not require a password (e.g. trust auth in pg_hba.conf), this can be left empty or omitted. Default: no password.
KRENALIS_DB_DATABASE PostgreSQL database name.
KRENALIS_DB_SCHEMA Schema within the PostgreSQL database to use.
Default: public
KRENALIS_DB_MAX_CONNECTIONS Maximum number of connections to PostgreSQL. Must be >= 2.
Default: 8

HTTP server

Variable Description
KRENALIS_HTTP_HOST Server address to bind to. It can be an IPv4 address, an IPv6 address, or a hostname. Examples: localhost, [::1].
Default: 127.0.0.1
KRENALIS_HTTP_PORT Port number on which the server listens. Example: 443.
Default: 2022
KRENALIS_HTTP_TLS_ENABLED Enable or disable TLS (HTTPS). You can disable TLS if a reverse proxy or load balancer in front of the Krenalis server is handling the TLS termination, as it will manage the encryption and decryption of traffic.
Default: false
KRENALIS_HTTP_TLS_CERT_FILE Path to the TLS certificate file (e.g., .crt file). It is required if TLS is enabled.
KRENALIS_HTTP_TLS_KEY_FILE Path to the private key file associated with the TLS certificate. It is required if TLS is enabled.
KRENALIS_HTTP_TLS_DNS_NAMES Comma-separated list of hostnames or IP addresses that the TLS certificate is expected to be valid for. Use this when Krenalis is behind a reverse proxy or load balancer and the connection to the Krenalis server still uses TLS. If not set, Krenalis derives the expected names from KRENALIS_HTTP_EXTERNAL_URL and KRENALIS_HTTP_EXTERNAL_EVENT_URL when they use https. If the certificate does not match one of them, Krenalis writes a warning to the log.
KRENALIS_HTTP_EXTERNAL_URL Public address through which the server can be accessed from outside the internal network. If not set, it is determined by the combination of KRENALIS_HTTP_TLS_ENABLED, KRENALIS_HTTP_HOST, and KRENALIS_HTTP_PORT. Example: https://krenalis.example.com:8080/.
KRENALIS_HTTP_EXTERNAL_EVENT_URL Public address through which the event ingestion endpoint (/v1/events) can be accessed from outside the internal network. If not set, it is the combination of the external URL and /v1/events. Example: https://krenalis.example.com:8080/v1/events.
KRENALIS_HTTP_READ_HEADER_TIMEOUT Max time to read request headers, including TLS handshake.
Default: 2s
KRENALIS_HTTP_READ_TIMEOUT Max time to read the full request (headers + body), starting from first byte.
Default: 5s
KRENALIS_HTTP_WRITE_TIMEOUT Max time for handler execution and sending response. For TLS, includes handshake.
Default: 30s
KRENALIS_HTTP_IDLE_TIMEOUT Max idle time between requests on keep-alive connections.
Default: 120s

NATS

Settings used to access the NATS server required by Krenalis.

When connecting to NATS, Krenalis passes all configured authentication parameters to the NATS server, which applies its authentication rules in the following order: NKey, token, username/password.

Variable Description
KRENALIS_NATS_URL One or more URLs, comma-separated, for a single server or multiple servers in the same NATS cluster. Each URL has the form <scheme>://<server>:<port>, where <scheme> can be nats, tls, ws, or wss. <server>:<port> is accepted and treated as nats://<server>:<port>. Default: nats://127.0.0.1:4222.
KRENALIS_NATS_NKEY Private key of a NATS user NKey (starts with SU). The corresponding public key (starts with UD) should be configured on the server.
KRENALIS_NATS_TOKEN Authentication token.
KRENALIS_NATS_USER Username used for authentication.
KRENALIS_NATS_PASSWORD Password associated with the specified user.
KRENALIS_NATS_STORAGE Storage backend used for streams. Supported values are file and memory. If the stream already exists, Krenalis verifies that it uses the configured storage type. If the stream already exists, its storage type must match this setting. If it does not, Krenalis fails to start and reports an error. Default: file.
KRENALIS_NATS_COMPRESSION Compression algorithm used for file-based storage. Supported values are unset (no compression) and s2. This setting requires file-based storage: if KRENALIS_NATS_STORAGE is set to memory, Krenalis fails to start. Default: no compression.
KRENALIS_NATS_REPLICAS Number of NATS cluster nodes used to replicate events. Common values are 1 (no replicas), 3, and 5. Values 2 and 4 are supported but rarely used. If the number of replicas exceeds the number of available NATS nodes, Krenalis fails to start and reports an error. Default: 1.

Team member emails and SMTP

Settings for emails that are sent to members.

Variable Description
KRENALIS_INVITE_MEMBERS_VIA_EMAIL Make the creation of new team members happen via email invitation.. Use true to allow adding members with email invitation.
Default: false
KRENALIS_MEMBER_EMAIL_FROM "From" address from which team member emails are sent (mandatory to send emails to members). Example: Org <org@example.com> or org@example.com.

If you enable the settings above, then you need to configure your SMTP server settings:

Variable Description
KRENALIS_SMTP_HOST SMTP server address.
KRENALIS_SMTP_PORT SMTP server port.
KRENALIS_SMTP_USERNAME SMTP username.
KRENALIS_SMTP_PASSWORD SMTP password.

General

Variable Description
KRENALIS_KMS Key management system used to store and access the master key that Krenalis uses to encrypt application data.

You can provide a raw key directly by setting the value to key:<base64-encoded 32-byte key>.

To use AWS KMS, set the value to aws:<key-id>, where <key-id> is the KMS key identifier (e.g., full ARN or alias such as alias/your-key). Ensure the appropriate AWS credentials and region configuration are available in the environment.

If the master key changes, Krenalis will no longer be able to decrypt previously encrypted data and will fail to start.

Required
KRENALIS_ORGANIZATIONS_API_KEY API key for the organizations management endpoints. When not set, these endpoints are disabled and return an authentication error. When set, requests must include it as a Bearer token in the Authorization header. Format: org_ followed by exactly 43 alphanumeric characters ([a-zA-Z0-9]), for a total of 47 characters. For more details, see the Organizations API key section.
KRENALIS_MAXMIND_DB_PATH Path to the MaxMind database file (usually with extension '.mmdb') for automatically adding geolocation information to the events. If not set, no geolocation information is automatically added to the events by Krenalis, so it is only possible to provide location information explicitly.
KRENALIS_TERMINATION_DELAY Delay time before gracefully shutting down the server. Example: 1s (1 second), 200ms (200 milliseconds).
Default: no delay
KRENALIS_JAVASCRIPT_SDK_URL URL that serves the JavaScript SDK.
Default: https://cdn.krenalis.com/krenalis.min.js
KRENALIS_TELEMETRY_LEVEL Level for telemetry data sent by Krenalis: none (no telemetry data will be sent), errors (only telemetry data related to errors will be sent), stats (only telemetry data related to software usage statistics will be sent), all (both types of telemetry data (errors and stats) will be sent).
Default: all
KRENALIS_PROMETHEUS_METRICS_ENABLED Enable or disable the /metrics endpoint for Prometheus monitoring.
Default: false
KRENALIS_EXTERNAL_ASSETS_URLS List of base URLs (comma-separated) from which Krenalis retrieves external assets (as icons) related to connector and data warehouse brands. If an image is not available at the first URL, the second is called, and so on, until eventually a default image is used.
Default: https://assets.krenalis.com/
KRENALIS_POTENTIAL_CONNECTORS_URL URL of the "potentials.json" connector file which contains the connectors that may be implemented in future versions of Krenalis. Set to none to not retrieve any file.
Default: https://assets.krenalis.com/admin/connectors/potentials.json
KRENALIS_MAX_QUEUED_EVENTS_PER_DESTINATION Maximum size of the event queue used by a destination connection to send events to an application. This value limits memory usage and also caps the maximum number of in-flight events. If not set, the default value is 50000. The minimum allowed value is 1. This setting may be replaced in the future by alternative memory control mechanisms.

Transformers

The following settings let you choose how transformations are executed. Krenalis can run them either using AWS Lambda or locally. In production, you must use AWS Lambda only. The local mode is meant for testing or evaluating Krenalis when running with Docker.

AWS Lambda

Accessing AWS Lambda is accomplished by reading the environment configuration to connect to AWS, as expected by Amazon AWS. In addition to this configuration, you must provide these environment variables to Krenalis to complete the Lambda configuration:

Variable Description
KRENALIS_TRANSFORMERS_PROVIDER Set to aws-lambda, to use the AWS Lambda provider for transformations.
KRENALIS_TRANSFORMERS_AWS_LAMBDA_ROLE AWS IAM Role ARN to be assumed for executing Lambda functions.
KRENALIS_TRANSFORMERS_AWS_LAMBDA_NODEJS_RUNTIME Node.js runtime version for AWS Lambda. Example: nodejs22.x.
KRENALIS_TRANSFORMERS_AWS_LAMBDA_NODEJS_LAYER (Optional) ARN of a Lambda layer for Node.js functions.
KRENALIS_TRANSFORMERS_AWS_LAMBDA_PYTHON_RUNTIME Python runtime version for AWS Lambda. Example: python3.14.
KRENALIS_TRANSFORMERS_AWS_LAMBDA_PYTHON_LAYER (Optional) ARN of a Lambda layer for Python functions.

⚠️ Once you have configured access to AWS Lambda and created pipelines with transformation functions, those pipelines will stop working if you change your AWS Lambda configuration by referencing another AWS Lambda instance.

Local

⚠️ Configuring transformers for local execution allows the code in transformation functions defined in Krenalis to execute arbitrary code on the local machine. Therefore, use with caution and only in trusted contexts.

Variable Description
KRENALIS_TRANSFORMERS_PROVIDER Set to local, to use the local provider for transformations..
KRENALIS_TRANSFORMERS_LOCAL_NODEJS_EXECUTABLE Path to the Node.js executable. Example: /usr/bin/node.
KRENALIS_TRANSFORMERS_LOCAL_PYTHON_EXECUTABLE Path to the Python executable. Example: /usr/bin/python.
KRENALIS_TRANSFORMERS_LOCAL_FUNCTIONS_DIR Directory where local transformation functions are stored (a subdirectory named krenalis-functions will be created inside the specified path). This directory should be writable by the user executing the Krenalis executable. Example: /var/krenalis-project.
KRENALIS_TRANSFORMERS_LOCAL_SUDO_USER System user under which to run local transformation function processes. Switching to this user is done in Krenalis via sudo. If left blank, the current user is retained and sudo is not invoked.
KRENALIS_TRANSFORMERS_LOCAL_DOAS_USER System user under which to run local transformation function processes. Switching to this user is done in Krenalis via doas. If left blank, the current user is retained and doas is not invoked.

If you want to change the file system location of the functions dir once you have already created pipelines with transformation functions, you need to (1) copy the krenalis-functions directory within the new desired location and (2) update the KRENALIS_TRANSFORMERS_LOCAL_FUNCTIONS_DIR environment variable to refer to that new location.

Static connector settings

The following are low-level settings related to the Krenalis installation that can be set only via environment variables.

File System

Variable Description
KRENALIS_CONNECTOR_FILESYSTEM_ROOT Directory used as root by File System connections. Mandatory when using File System connections.
KRENALIS_CONNECTOR_FILESYSTEM_DISPLAYED_ROOT Directory displayed as root by File System connections. This is purely visual, useful in cases where you want to display a different root than the actual one in the Krenalis interface (e.g., symlinks or directories mounted on virtual volumes).