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

# Variables de entorno de la API de Cabine

> Las variables de entorno que configuran la API de Cabine.

La API de Cabine lee su configuración de variables de entorno cuando inicia. Para cambiar un valor, reinicia el servicio. Para la configuración de Lerian Cabine en el navegador, consulta [Configuración de Lerian Cabine](https://docs.lerian.studio/es/rails/cabine/cabine-configuration.md).

En las tablas siguientes, **Obligatorio** marca una variable que debes definir: **Sí** para cualquier despliegue, o la condición indicada. `—` significa que no hay valor predeterminado. Las condiciones usan dos términos:

* **Entorno de producción**: `ENV_NAME` es `production` o `prod`.
* **Entorno de desarrollo**: `ENV_NAME` es `development`, `develop`, `dev`, `local` o `test`.

Las variables que guardan una duración usan el formato de duración de Go, por ejemplo `15m` o `24h`. Una duración que no se puede leer se reemplaza por su valor predeterminado. Una duración igual o menor que cero en una variable `DESK_` detiene el inicio. Un número que no se puede leer también se reemplaza por su valor predeterminado.

## Runtime y servidor

| Variable | Descripción | Predeterminado | Obligatorio |
| - | - | - | - |
| `ENV_NAME` | El nombre del entorno. | `development` | No |
| `LOG_LEVEL` | El nivel de log. | `info` | No |
| `SERVER_PORT` | El puerto del servidor HTTP. | `3002` | No |
| `DEPLOYMENT_MODE` | `local`, `byoc` o `saas`. Cualquier otro valor detiene el inicio. | `local` | En un entorno de producción |
| `DESK_CORS_ALLOWED_ORIGINS` | Los orígenes del navegador que pueden llamar a la API de Cabine. Defínela con el origen donde los operadores abren Cabine. | — | No |

`DEPLOYMENT_MODE` definido como `saas` también exige estos valores:

* `ENV_NAME` es `production`, `prod` o `staging`.
* `DB_SSLMODE` es `require`, `verify-ca` o `verify-full`.
* `PLUGIN_AUTH_ADDRESS`, `PLUGIN_ACCESS_MANAGER_URL` y `DESK_SPI_CALLBACK_URL` usan `https` cuando están definidas.

`DESK_CORS_ALLOWED_ORIGINS` es una lista que separas con comas. Escribe cada origen como `scheme://host[:port]`, con `http` o `https`, un host en minúsculas, sin puerto predeterminado, sin ruta, sin query y sin credenciales. Un comodín o una entrada en otra forma detiene el inicio. Un valor vacío no agrega encabezados de CORS.

## Base de datos

| Variable | Descripción | Predeterminado | Obligatorio |
| - | - | - | - |
| `DB_HOST` | El host de PostgreSQL. | — | Sí |
| `DB_PORT` | El puerto de PostgreSQL. | `5432` | No |
| `DB_USER` | El usuario de PostgreSQL. | — | Sí |
| `DB_PASSWORD` | La contraseña de PostgreSQL. Sensible. | — | No |
| `DB_NAME` | El nombre de la base de datos. | — | Sí |
| `DB_SSLMODE` | El modo SSL de PostgreSQL. Un valor distinto de `require`, `verify-ca` o `verify-full` detiene el inicio, a menos que `ALLOW_INSECURE_TLS` sea `true`. | `disable` | No |
| `DB_MAX_OPEN_CONNS` | El número máximo de conexiones abiertas. | `25` | No |
| `DB_MAX_IDLE_CONNS` | El número máximo de conexiones inactivas. | `10` | No |
| `DB_CONN_MAX_LIFETIME` | La edad máxima de una conexión. | `10m` | No |
| `DB_CONN_MAX_IDLE_TIME` | El tiempo inactivo máximo de una conexión. | `5m` | No |

## Telemetría

| Variable | Descripción | Predeterminado | Obligatorio |
| - | - | - | - |
| `ENABLE_TELEMETRY` | Define `true` para exportar traces y métricas. Si la telemetría no puede iniciar, la API de Cabine registra un error y sigue en ejecución. | `false` | No |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | El endpoint del colector OTLP. | — | No |
| `METRICS_PROMETHEUS_ENABLED` | Define `true` para servir métricas de Prometheus en un listener separado. | `false` | No |
| `METRICS_PROMETHEUS_ADDRESS` | La dirección del listener de Prometheus. | `127.0.0.1:9074` | No |

## Autenticación

La API de Cabine verifica los permisos de cada solicitud con Access Manager. Consulta [Acceso y roles](https://docs.lerian.studio/es/rails/cabine/cabine-access-and-roles.md).

| Variable | Descripción | Predeterminado | Obligatorio |
| - | - | - | - |
| `PLUGIN_AUTH_ENABLED` | Activa o desactiva la verificación de permisos. Define `true` o `false`. Un valor en blanco u otro valor detiene el inicio. `false` inicia solo en un entorno de desarrollo, y nunca con `DEPLOYMENT_MODE=saas`. | — | Sí |
| `PLUGIN_AUTH_ADDRESS` | La dirección del servicio de autenticación de Access Manager, sin `/v1`. La API de Cabine también la usa para obtener las credenciales de sus llamadas a Access Manager y a Lerian SPI. | — | Sí, cuando `PLUGIN_AUTH_ENABLED` es `true`. |

`PLUGIN_AUTH_ENABLED=false` no se acepta cuando `ENV_NAME` no está definida. Un `ENV_NAME` sin definir no cuenta como entorno de desarrollo.

## Llamadas a Access Manager

Después de que otro administrador de la API de Cabine aprueba la eliminación de un usuario operador, la API de Cabine elimina al usuario en Access Manager. Se autentica como una aplicación de Access Manager. Consulta [Administración](https://docs.lerian.studio/es/rails/cabine/cabine-administration.md).

| Variable | Descripción | Predeterminado | Obligatorio |
| - | - | - | - |
| `PLUGIN_ACCESS_MANAGER_URL` | La dirección del servicio de identidad de Access Manager, sin `/v1`, donde la API de Cabine elimina usuarios. Sin ella, la API de Cabine no puede eliminar a un usuario. | — | En un entorno de producción |
| `PLUGIN_ACCESS_MANAGER_CLIENT_ID` | El client ID de la aplicación de Access Manager. | — | Si la dirección está definida, y en un entorno de producción |
| `PLUGIN_ACCESS_MANAGER_CLIENT_SECRET` | El client secret de la aplicación de Access Manager. Sensible. | — | Si la dirección está definida, y en un entorno de producción |

## Llamadas a Lerian SPI

Después de una aprobación, la API de Cabine envía la decisión a Lerian SPI. Se autentica como una aplicación de Access Manager. Concede `br-spi-operations:update` en Lerian SPI a esta aplicación. Consulta [Aprobaciones de revisión manual](https://docs.lerian.studio/es/rails/cabine/cabine-manual-review-approvals.md).

| Variable | Descripción | Predeterminado | Obligatorio |
| - | - | - | - |
| `DESK_SPI_CALLBACK_URL` | La dirección del servicio DICT de Lerian SPI, sin `/api/v1/dict`. Sin ella, ninguna decisión aprobada llega a Lerian SPI. | — | En un entorno de producción |
| `DESK_SPI_CALLBACK_CLIENT_ID` | El client ID de la aplicación de Access Manager. | — | Si la dirección está definida, y en un entorno de producción |
| `DESK_SPI_CALLBACK_CLIENT_SECRET` | El client secret de la aplicación de Access Manager. Sensible. | — | Si la dirección está definida, y en un entorno de producción |
| `DESK_OPERATION_APPROVAL_DECISION_WINDOW` | El tiempo que tiene la persona que decide después de una propuesta. | `24h` | No |
| `DESK_OPERATION_APPROVAL_EXPIRY_SWEEP_INTERVAL` | Cada cuánto la API de Cabine define el estado `expired` en las propuestas atrasadas. | `5m` | No |
| `DESK_APPROVAL_DELIVERY_SWEEP_INTERVAL` | Cada cuánto la API de Cabine vuelve a intentar entregar las decisiones que Lerian SPI no aceptó. | `1m` | No |
| `DESK_APPROVAL_DELIVERY_BACKOFF_BASE` | La espera después del primer intento que falló. La espera se duplica con cada fallo. | `30s` | No |
| `DESK_APPROVAL_DELIVERY_BACKOFF_MAX` | La espera más larga entre intentos. No puede ser menor que la base. | `30m` | No |
| `DESK_APPROVAL_DELIVERY_STALE_AFTER` | La edad de la decisión no entregada más antigua en la que el resultado de readiness de Lerian SPI la informa. El mismo período limita las decisiones rehusadas que este resultado informa. | `1h` | No |
| `DESK_APPROVAL_DELIVERY_MAX_ATTEMPTS` | El número de intentos, con el primero, antes de que el resultado sea `exhausted`. Debe ser mayor que cero. | `20` | No |

## Retención

| Variable | Descripción | Predeterminado | Obligatorio |
| - | - | - | - |
| `DESK_ACK_TTL` | Cuánto tiempo guarda la API de Cabine una confirmación de alerta y una solicitud de eliminación de usuario. Pasado ese tiempo, elimina el registro. | `720h` | No |
| `DESK_ACK_GC_INTERVAL` | Cada cuánto la API de Cabine elimina los registros vencidos. | `1h` | No |

## Reglas del entorno de producción

En un entorno de producción, el inicio se detiene a menos que estas variables tengan un valor:

* `PLUGIN_AUTH_ADDRESS`
* `PLUGIN_ACCESS_MANAGER_URL`, `PLUGIN_ACCESS_MANAGER_CLIENT_ID` y `PLUGIN_ACCESS_MANAGER_CLIENT_SECRET`
* `DESK_SPI_CALLBACK_URL`, `DESK_SPI_CALLBACK_CLIENT_ID` y `DESK_SPI_CALLBACK_CLIENT_SECRET`
* `DEPLOYMENT_MODE`

En cualquier entorno, una dirección sin su client ID y su client secret detiene el inicio.

## Salud y readiness

La API de Cabine sirve `/health`, `/readyz` y `/version` en su puerto HTTP. `/readyz` responde `200` cuando el servicio está listo y `503` cuando no lo está. Si la API de Cabine no puede acceder a la base de datos al iniciar, el inicio se detiene. Si otra dependencia no está lista al iniciar, el servicio sigue en ejecución y permanece no listo.

El resultado de readiness cubre estas dependencias:

* La base de datos: la API de Cabine puede alcanzarla.
* El esquema de la base de datos: está en la versión actual. Aplica las migraciones de la base de datos antes de iniciar el servicio.
* Access Manager: el servicio se omite cuando `PLUGIN_ACCESS_MANAGER_URL` no está definida. Una dirección que no responde deja el servicio no listo.
* Lerian SPI: el servicio se omite cuando `DESK_SPI_CALLBACK_URL` no está definida. Un Lerian SPI que no responde, una decisión antigua no entregada, una decisión que Lerian SPI rehusó o una decisión agotada aparece como un motivo. Esto no deja el servicio no listo.


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