Environment Variables

Environment variables

There are two ways to use the environment with BxLens:

1. BxLens variables. A few fixed variables that start with BXLENS_. They name the server, its store folder and its secrets key.
2. The BoxLang convention. BoxLang can override any setting of boxlang.json from the environment, and that includes every BxLens setting.

Set them in the environment of the server process: a service file, a Dockerfile, a Compose file or a Kubernetes manifest.

BxLens variables

In a container the host name changes on every deploy. Set BXLENS_SERVER_NAME and BXLENS_INSTANCE to fixed values.

Variables whose name you choose

These settings hold the name of a variable, never its value. For the first two, the name must start with the prefix shown, so a setting cannot send out any other variable of the server (a license, a cloud key).

Passwords in boxlang.json

BoxLang replaces ${env.NAME} in boxlang.json itself. Any name works. These are the ones the documentation uses:

"console": {
    "password": "${env.BXLENS_PASSWORD}",
    "viewerPassword": "${env.BXLENS_VIEWER_PASSWORD}"
}

A default is allowed: ${env.BXLENS_PASSWORD:change-me}.

The BoxLang convention: any setting from the environment

BoxLang lets any item of its configuration be overridden from the environment or from a Java system property. The BxLens settings live under modules.bxlens.settings, so the same rule applies to them. See Environmental properties configuration in the BoxLang documentation.

The rule. Start with BOXLANG_, then the path of the setting with each dot written as _:

modules.bxlens.settings.console.sessionStorage
        |
BOXLANG_MODULES_BXLENS_SETTINGS_CONSOLE_SESSIONSTORAGE

Examples

BOXLANG_MODULES_BXLENS_SETTINGS_CONSOLE_SESSIONSTORAGE=cache
BOXLANG_MODULES_BXLENS_SETTINGS_CONSOLE_SESSIONCACHE=SESSIONS
BOXLANG_MODULES_BXLENS_SETTINGS_THRESHOLDS_SLOWQUERYMS=250

The same setting as a Java system property uses dots and the exact case, and needs the boxlang. prefix:

-Dboxlang.modules.bxlens.settings.console.sessionStorage=cache

Good to know

• Case. The variable name is not case sensitive. BoxLang matches it to the key that is already in boxlang.json, and BxLens reads its settings without regard to case too.
• Keys that are not in boxlang.json. They are added, and nested paths work.
• Values. Every value arrives as a text. BxLens turns the text into a boolean or a number where the setting needs one, so true, false and 250 work.
• Lists. A list (for example access.proxyPeers) does not arrive as a list. Set lists in boxlang.json.
• The prefix BXLENS_SETTINGS_ is not a thing. BXLENS_SETTINGS_CONSOLE_SESSIONSTORAGE is ignored. Use the BOXLANG_MODULES_BXLENS_SETTINGS_ form.
• Settings of the console. A setting that an admin changed in the console is kept in the settings file of the store and is a separate layer. See Configuration.

Variables of the platform

BxLens only asks whether these are set, never for their value, to tell where the server runs. Do not set them yourself.

BxLens also reads BOXLANG_INSTANCE_NAME (the BoxLang runtime instance name), COMMANDBOX_VERSION (the CommandBox version) and, for the host name, HOSTNAME or COMPUTERNAME.

All variables on one page