> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Cabine API environment variables

> The environment variables that set up the Cabine API.

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](https://docs.lerian.studio/en/rails/cabine/cabine-configuration.md).

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](https://docs.lerian.studio/en/rails/cabine/cabine-access-and-roles.md).

| 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](https://docs.lerian.studio/en/rails/cabine/cabine-administration.md).

| 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](https://docs.lerian.studio/en/rails/cabine/cabine-manual-review-approvals.md).

| 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.