Cabine API environment variables

The Cabine API reads its settings from environment variables when it starts. To change a value, restart the service. For the settings of Lerian Cabine in the browser, see Configuring Lerian Cabine. In the tables below, Required marks a variable that you must set: Yes for any deployment, or the condition named. — means no default. The conditions use two terms:

Production environment: ENV_NAME is production or prod.
Development environment: ENV_NAME is development, develop, dev, local or test.

Variables that hold a duration use the Go duration format, for example 15m or 24h. A duration that cannot be read is replaced by its default. A duration of zero or less in a DESK_ variable stops startup. A number that cannot be read is replaced by its default too.

Runtime and server

Variable	Description	Default	Required
`ENV_NAME`	The environment name.	`development`	No
`LOG_LEVEL`	The log level.	`info`	No
`SERVER_PORT`	The port of the HTTP server.	`3002`	No
`DEPLOYMENT_MODE`	`local`, `byoc` or `saas`. Any other value stops startup.	`local`	In a production environment
`DESK_CORS_ALLOWED_ORIGINS`	The browser origins that can call the Cabine API. Set it to the origin where operators open Cabine.	—	No

DEPLOYMENT_MODE set to saas also needs these values:

ENV_NAME is production, prod or staging.
DB_SSLMODE is require, verify-ca or verify-full.
PLUGIN_AUTH_ADDRESS, PLUGIN_ACCESS_MANAGER_URL and DESK_SPI_CALLBACK_URL use https when they are set.

DESK_CORS_ALLOWED_ORIGINS is a list that you separate with commas. Write each origin as scheme://host[:port], with http or https, a lowercase host, no default port, no path, no query and no credentials. A wildcard or an entry in another form stops startup. An empty value adds no CORS headers.

Database

Variable	Description	Default	Required
`DB_HOST`	The PostgreSQL host.	—	Yes
`DB_PORT`	The PostgreSQL port.	`5432`	No
`DB_USER`	The PostgreSQL user.	—	Yes
`DB_PASSWORD`	The PostgreSQL password. Sensitive.	—	No
`DB_NAME`	The database name.	—	Yes
`DB_SSLMODE`	The PostgreSQL SSL mode. A value other than `require`, `verify-ca` or `verify-full` stops startup unless `ALLOW_INSECURE_TLS` is `true`.	`disable`	No
`DB_MAX_OPEN_CONNS`	The maximum number of open connections.	`25`	No
`DB_MAX_IDLE_CONNS`	The maximum number of idle connections.	`10`	No
`DB_CONN_MAX_LIFETIME`	The maximum age of a connection.	`10m`	No
`DB_CONN_MAX_IDLE_TIME`	The maximum idle time of a connection.	`5m`	No

Telemetry

Variable	Description	Default	Required
`ENABLE_TELEMETRY`	Set `true` to export traces and metrics. If telemetry cannot start, the Cabine API logs an error and keeps running.	`false`	No
`OTEL_EXPORTER_OTLP_ENDPOINT`	The OTLP collector endpoint.	—	No
`METRICS_PROMETHEUS_ENABLED`	Set `true` to serve Prometheus metrics on a separate listener.	`false`	No
`METRICS_PROMETHEUS_ADDRESS`	The address of the Prometheus listener.	`127.0.0.1:9074`	No

Authentication

The Cabine API checks the permissions of each request with Access Manager. See Access and roles.

Variable	Description	Default	Required
`PLUGIN_AUTH_ENABLED`	Turns the permission check on or off. Set `true` or `false`. A blank or other value stops startup. `false` starts only in a development environment, and never with `DEPLOYMENT_MODE=saas`.	—	Yes
`PLUGIN_AUTH_ADDRESS`	The address of the Access Manager auth service, without `/v1`. The Cabine API also uses it to get the credentials for its calls to Access Manager and Lerian SPI.	—	Yes, when `PLUGIN_AUTH_ENABLED` is `true`.

PLUGIN_AUTH_ENABLED=false is not accepted when ENV_NAME is not set. An unset ENV_NAME does not count as a development environment.

Calls to Access Manager

After a different Cabine API admin approves the deletion of an operator user, the Cabine API deletes the user in Access Manager. It signs in as an Access Manager application. See Administration.

Variable	Description	Default	Required
`PLUGIN_ACCESS_MANAGER_URL`	The address of the Access Manager identity service, without `/v1`, where the Cabine API deletes users. Without it, the Cabine API cannot delete a user.	—	In a production environment
`PLUGIN_ACCESS_MANAGER_CLIENT_ID`	The client ID of the Access Manager application.	—	If the address is set, and in a production environment
`PLUGIN_ACCESS_MANAGER_CLIENT_SECRET`	The client secret of the Access Manager application. Sensitive.	—	If the address is set, and in a production environment

Calls to Lerian SPI

After an approval, the Cabine API sends the decision to Lerian SPI. It signs in as an Access Manager application. Grant br-spi-operations:update on Lerian SPI to this application. See Manual review approvals.

Variable	Description	Default	Required
`DESK_SPI_CALLBACK_URL`	The address of the Lerian SPI DICT service, without `/api/v1/dict`. Without it, no approved decision reaches Lerian SPI.	—	In a production environment
`DESK_SPI_CALLBACK_CLIENT_ID`	The client ID of the Access Manager application.	—	If the address is set, and in a production environment
`DESK_SPI_CALLBACK_CLIENT_SECRET`	The client secret of the Access Manager application. Sensitive.	—	If the address is set, and in a production environment
`DESK_OPERATION_APPROVAL_DECISION_WINDOW`	The time that the person who decides has after a proposal.	`24h`	No
`DESK_OPERATION_APPROVAL_EXPIRY_SWEEP_INTERVAL`	How often the Cabine API sets the state `expired` on late proposals.	`5m`	No
`DESK_APPROVAL_DELIVERY_SWEEP_INTERVAL`	How often the Cabine API tries again to deliver decisions that Lerian SPI did not accept.	`1m`	No
`DESK_APPROVAL_DELIVERY_BACKOFF_BASE`	The wait after the first failed attempt. The wait doubles after each failure.	`30s`	No
`DESK_APPROVAL_DELIVERY_BACKOFF_MAX`	The longest wait between attempts. It must not be less than the base.	`30m`	No
`DESK_APPROVAL_DELIVERY_STALE_AFTER`	The age of the oldest undelivered decision at which the readiness result of Lerian SPI reports it. The same period limits the refused decisions that this result reports.	`1h`	No
`DESK_APPROVAL_DELIVERY_MAX_ATTEMPTS`	The number of attempts, with the first one, before the outcome is `exhausted`. It must be more than zero.	`20`	No

Retention

Variable	Description	Default	Required
`DESK_ACK_TTL`	How long the Cabine API keeps an alert acknowledgement and a user deletion request. After that time, it deletes the record.	`720h`	No
`DESK_ACK_GC_INTERVAL`	How often the Cabine API deletes expired records.	`1h`	No

Production environment rules

In a production environment, startup stops unless these variables hold a value:

PLUGIN_AUTH_ADDRESS
PLUGIN_ACCESS_MANAGER_URL, PLUGIN_ACCESS_MANAGER_CLIENT_ID and PLUGIN_ACCESS_MANAGER_CLIENT_SECRET
DESK_SPI_CALLBACK_URL, DESK_SPI_CALLBACK_CLIENT_ID and DESK_SPI_CALLBACK_CLIENT_SECRET
DEPLOYMENT_MODE

In any environment, an address without its client ID and client secret stops startup.

Health and readiness

The Cabine API serves /health, /readyz and /version on its HTTP port. /readyz answers 200 when the service is ready and 503 when it is not. If the Cabine API cannot reach the database at startup, startup stops. If another dependency is not ready at startup, the service keeps running and stays not ready. The readiness result covers these dependencies:

The database: the Cabine API can reach it.
The database schema: it is at the current version. Apply the database migrations before you start the service.
Access Manager: the service is skipped when PLUGIN_ACCESS_MANAGER_URL is not set. An address that does not answer makes the service not ready.
Lerian SPI: the service is skipped when DESK_SPI_CALLBACK_URL is not set. A Lerian SPI that does not answer, an old undelivered decision, a refused decision or an exhausted decision appears as a reason. It does not make the service not ready.

​Runtime and server

​Database

​Telemetry

​Authentication

​Calls to Access Manager

​Calls to Lerian SPI

​Retention

​Production environment rules

​Health and readiness