> ## 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.
# Fundamentos de configuración BYOC
> Consulta las variables de entorno compartidas por los servicios Go de Lerian, con valores posibles, para desplegar en tu propia infraestructura (BYOC).
En un despliegue BYOC (bring your own cloud), ejecutas los productos de Lerian dentro de tu propia infraestructura de AWS, GCP o en las instalaciones, y eres dueño de los datos y del entorno de ejecución. Cada servicio se configura mediante variables de entorno, y la mayoría de ellas son específicas del servicio. Esta página cubre la **base universal** —las variables que se comportan igual en todos los servicios Go de Lerian— para que definas los ajustes de todo el despliegue una sola vez y luego recurras a la página propia de cada producto para el resto.
Esta es la base compartida, no la lista completa. Los prefijos de las variables difieren ligeramente entre servicios (por ejemplo, un servicio con bases de datos de onboarding y de transacciones separadas les asigna espacios de nombres distintos), y cada servicio añade sus propias claves. Consulta [Variables por producto](#variables-por-producto) para ver las listas exhaustivas.
## Modo de despliegue y TLS
`DEPLOYMENT_MODE` define con qué rigor el servicio impone TLS en sus conexiones de infraestructura, y su valor se refleja en la respuesta de [`/readyz`](/es/reference/health-and-readiness).
| Variable | Descripción | Valor por defecto | Valores permitidos |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ----------------------- |
| `DEPLOYMENT_MODE` | Postura de imposición de TLS. `local` permite conexiones en texto plano. `byoc` recomienda TLS y advierte sobre el texto plano, pero aun así arranca. `saas` hace obligatorio el TLS: el servicio se niega a arrancar si alguna conexión a una dependencia carece de TLS. | `local` | `local`, `byoc`, `saas` |
| `ALLOW_INSECURE_TLS` | Omite la imposición de TLS por conexión en los DSN de infraestructura. Pensado solo para desarrollo local. | `false` | `true`, `false` |
Para un despliegue BYOC de producción, define `DEPLOYMENT_MODE=byoc`, conecta cada almacén de datos por TLS y deja `ALLOW_INSECURE_TLS` sin definir (`false`). Los valores por defecto de `local` entregan conexiones en texto plano y no son seguros para producción.
## Servidor
| Variable | Descripción | Valor por defecto | Valores permitidos |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----------------------------------------------------------- |
| `SERVER_ADDRESS` | Dirección principal de escucha HTTP (`host:port`, normalmente `:port`). Las sondas de liveness, readiness y versión se enlazan a este mismo puerto. | Varía por servicio | `host:port` |
| `LOG_LEVEL` | Verbosidad de los logs. Usa `info` o superior en producción. | `debug` | `debug`, `info`, `warn`, `error` |
| `ENV_NAME` | Etiqueta del entorno. En SLC, se normaliza a una lista permitida. | `development` | SLC: `production`, `staging`, `uat`, `development`, `local` |
| `VERSION` | Etiqueta de versión del servicio expuesta por `/version`. | Por release | Cadena semver |
Algunos servicios exponen un `SERVER_PORT` numérico en lugar de, o junto con, `SERVER_ADDRESS`. Los componentes de tipo worker sin una API HTTP principal exponen un puerto de salud dedicado (por ejemplo `HEALTH_PORT` o `WORKER_SERVER_PORT`). Consulta [Puertos de red por defecto](/es/reference/default-network-ports) y [Salud y readiness](/es/reference/health-and-readiness).
## Almacenes de datos
Cada servicio que persiste estado se conecta a uno o más almacenes de datos. El prefijo de la variable depende del almacén y, en algunos servicios, de la base de datos lógica. La tabla siguiente muestra la forma común; consulta la página de cada producto para los nombres exactos.
| Variable | Descripción | Valor por defecto | Valores permitidos |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------ |
| `POSTGRES_HOST` / `POSTGRES_PORT` | Host y puerto de PostgreSQL. | — / `5432` | Host / puerto |
| `POSTGRES_USER` / `POSTGRES_PASSWORD` | Credenciales de conexión. La contraseña es un secreto: inyéctala en el momento del despliegue, nunca la incluyas en el control de versiones. | — | Cadena / secreto |
| `POSTGRES_NAME` / `POSTGRES_DB` / `DB_NAME` | Nombre de la base de datos. La clave exacta varía según el servicio: `POSTGRES_NAME` (por ejemplo STA, SLC, SISBAJUD, Consignado), `POSTGRES_DB` (SPB, SPI, Boleto) o `DB_NAME` (Pix Indirecto); Midaz la asigna por base de datos lógica como `DB_{MODULE}_NAME`. Consulta la página de cada producto. | — | Cadena |
| `POSTGRES_SSLMODE` | Modo TLS de libpq. Usa `require` o más estricto en producción. | `disable` | `disable`, `require`, `verify-ca`, `verify-full` |
| `POSTGRES_REPLICA_*` | Conexión opcional a una réplica de lectura (misma forma que la primaria). | — | Host / puerto / credenciales |
| `MONGO_URI` / `MONGO_HOST` / `MONGO_PORT` | Conexión a MongoDB, como URI completa o host y puerto discretos. | — | Cadena de conexión / host / puerto |
| `MONGO_TLS_CA_CERT` | Certificado CA PEM codificado en base64 para TLS (por ejemplo, un servicio MongoDB gestionado). | — | PEM base64 |
| `REDIS_HOST` / `REDIS_PASSWORD` | Endpoint de Redis/Valkey y contraseña de autenticación (secreto). | — | `host:port` / secreto |
| `REDIS_TLS` / `REDIS_CA_CERT` | Habilita TLS hacia Redis y proporciona un certificado CA PEM codificado en base64. En SLC, `REDIS_TLS=true` requiere un `REDIS_CA_CERT` no vacío. | `false` / — | `true`, `false` / PEM base64 |
| `RABBITMQ_HOST` / `RABBITMQ_URI` | Host del broker y esquema de conexión. Usa `amqps` en producción. | — / `amqp` | Host / `amqp`, `amqps` |
| `RABBITMQ_DEFAULT_USER` / `RABBITMQ_DEFAULT_PASS` | Credenciales del broker (la contraseña es un secreto). En SLC, cuando RabbitMQ está habilitado y su URL no tiene credenciales, declara explícitamente tanto `RABBITMQ_DEFAULT_USER` como `RABBITMQ_DEFAULT_PASS`. | — | Cadena / secreto |
No todos los servicios usan todos los almacenes, y los prefijos varían: los productos centrales suelen asignar espacios de nombres a las conexiones por base de datos lógica (por ejemplo `DB_ONBOARDING_*`, `DB_TRANSACTION_*`, `MONGO_CRM_*`), mientras que los plugins y los rieles usan la forma plana `POSTGRES_*` anterior. En modo multi-tenant, las credenciales estáticas de los almacenes de datos se ignoran: las conexiones se resuelven por tenant (ver más abajo).
## Multi-tenancy
El multi-tenancy está **desactivado por defecto**. Cuando lo habilitas, cada conexión a un almacén de datos pasa de la configuración estática a la resolución por tenant a través de Tenant Manager, y el servicio añade una sonda de readiness por tenant en `GET /readyz/tenant/{id}`.
| Variable | Descripción | Valor por defecto | Valores permitidos |
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------ |
| `MULTI_TENANT_ENABLED` | Habilita la resolución de conexiones por tenant. Cuando es `false`, el servicio se ejecuta en modo single-tenant con las conexiones estáticas anteriores. | `false` | `true`, `false` |
| `MULTI_TENANT_URL` | URL de la API de Tenant Manager. Obligatoria cuando está habilitado. | — | URL |
| `MULTI_TENANT_SERVICE_API_KEY` | Clave de API para Tenant Manager (secreto). Obligatoria cuando está habilitado. | — | Secreto |
| `MULTI_TENANT_ALLOW_INSECURE_HTTP` | Permite una URL de Tenant Manager en `http://` en texto claro. Nunca la habilites en producción: las credenciales viajan en texto plano. | `false` | `true`, `false` |
| `MULTI_TENANT_REDIS_HOST` / `MULTI_TENANT_REDIS_PORT` | Endpoint de Redis opcional para eventos de ciclo de vida de tenants (descubrimiento basado en eventos). | — / `6379` | Host / puerto |
Existen ajustes adicionales por servicio para dimensionar el pool por tenant, el circuit breaker y el TTL de caché (`MULTI_TENANT_MAX_TENANT_POOLS`, `MULTI_TENANT_CIRCUIT_BREAKER_*`, `MULTI_TENANT_CACHE_TTL_SEC`, y otros). Consulta las páginas por producto.
## Configuración en tiempo de ejecución
| Variable | Descripción | Valor por defecto | Valores permitidos |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ------------------ |
| `SYSTEMPLANE_ENABLED` | Habilita la API de administración de configuración en tiempo de ejecución de Systemplane en el puerto principal. Desactivada por defecto en la mayoría de los servicios; algunos —por ejemplo SPI— la activan por defecto. Consulta la página de cada servicio. | `false` (SPI: `true`) | `true`, `false` |
Cuando está habilitada, el servicio expone un plano autenticado para leer y escribir la configuración en tiempo de ejecución. Consulta [Systemplane](/es/reference/systemplane/overview) para la API, los espacios de nombres y los permisos requeridos.
## Streaming y outbox
La ruta de publicación de eventos (un productor de lib-streaming respaldado por un outbox transaccional) está **desactivada por defecto** en la mayoría de los servicios. Hay dos tipos de excepción: el worker de Fetcher exige un `STREAMING_ENABLED=true` explícito para emitir eventos de finalización de trabajos y se niega a arrancar sin él, y los rieles nativos (por ejemplo, [SPI](/es/rails/native/spi/spi-environment-variables#outbox-y-streaming) y [SILOC](/es/rails/native/siloc/siloc-environment-variables#observabilidad)) no exponen `STREAMING_ENABLED` en absoluto. El streaming en esos rieles no tiene modo desactivado: `STREAMING_BROKERS` es obligatoria, y el servicio se niega a arrancar cuando falta o es inválida. Consulta la página de cada producto para conocer su contrato.
| Variable | Descripción | Valor por defecto | Valores permitidos |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | --------------------------------------- |
| `STREAMING_ENABLED` | Habilita el productor de eventos, en los servicios que exponen el interruptor. El worker de Fetcher exige que este valor sea explícitamente `true`. Los rieles nativos no leen esta variable: su streaming está siempre activo. | `false` | `true`, `false` |
| `STREAMING_BROKERS` | Brokers de arranque de Kafka/RedPanda, como una lista `host:port` separada por comas. Los servicios cuyo streaming no tiene modo desactivado la exigen al arrancar. | — | CSV de `host:port` |
| `STREAMING_CLOUDEVENTS_SOURCE` | El `source` de CloudEvents estampado en cada evento que emite el servicio. No tiene valor por defecto: un productor que transmite a un broker con este valor vacío se detiene al arrancar. Varios productos aceptan exactamente un literal y se niegan a arrancar con cualquier otro, así que toma el valor de la página del propio producto. | — | El literal que exige el producto |
| `STREAMING_EVENT_POLICIES` | Anulaciones de la política de entrega por evento, como entradas `event.key.atributo=valor` separadas por comas, puntos y comas o saltos de línea (por ejemplo, `transaction.created.enabled=true,transaction.created.outbox=always`). Los atributos son `enabled`, `direct`, `outbox` y `dlq`. Vacía mantiene la política por defecto de cada evento. | — | Lista de `event.key.atributo=valor` |
| `STREAMING_COMPRESSION` | Códec de compresión del productor. | `lz4` | `none`, `gzip`, `snappy`, `lz4`, `zstd` |
| `STREAMING_REQUIRED_ACKS` | Nivel de confirmación del productor. | `all` | `all`, `leader`, `none` |
| `OUTBOX_ENABLED` | Habilita el despachador de outbox transaccional (cuando el servicio lo expone por separado). | `false` | `true`, `false` |
`STREAMING_SASL_*` y `STREAMING_TLS_*` aseguran la conexión al broker: defínelas cuando tu broker requiera autenticación o TLS.
## Descubrimiento de servicios
El descubrimiento de servicios con Consul está **desactivado por defecto**. Cuando está habilitado, el servicio se registra a sí mismo y resuelve a sus pares a través de Consul en lugar de direcciones estáticas.
| Variable | Descripción | Valor por defecto | Valores permitidos |
| --------------------------------------------- | --------------------------------------------------------------------------------- | ----------------- | ------------------ |
| `SD_ENABLED` | Habilita el descubrimiento de servicios con Consul. | `false` | `true`, `false` |
| `SD_ADDRESS` | Dirección del agente de Consul. Obligatoria cuando está habilitado. | — | `host:port` |
| `SD_EXTERNAL_ADDRESS` / `SD_INTERNAL_ADDRESS` | Direcciones anunciadas. Obligatorias cuando está habilitado. | — | `host:port` |
| `SD_TLS` / `SD_TLS_SKIP_VERIFY` | Habilita TLS hacia Consul y (por separado) omite la verificación del certificado. | `false` | `true`, `false` |
| `SD_TOKEN` | Token ACL de Consul (secreto). | — | Secreto |
Algunos servicios usan alias heredados (`SD_ADVERTISE_*`, `CONSUL_ADDR`) para el mismo comportamiento.
## Observabilidad
La telemetría es basada en push (OTLP). Algunos servicios exponen además un endpoint `/metrics` para el scraping de Prometheus; consulta [Salud y readiness](/es/reference/health-and-readiness).
| Variable | Descripción | Valor por defecto | Valores permitidos |
| -------------------------------------- | ----------------------------------------------------------------------------- | ------------------------ | ------------------ |
| `ENABLE_TELEMETRY` | Habilita la instrumentación de OpenTelemetry. | `false` | `true`, `false` |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint del colector OTLP. Obligatorio cuando la telemetría está habilitada. | — | URL |
| `OTEL_EXPORTER_OTLP_PORT` | Puerto OTLP, al usar host y puerto discretos. | `4317` | Puerto |
| `OTEL_RESOURCE_SERVICE_NAME` | Nombre del servicio adjunto a la telemetría exportada. | Por defecto del servicio | Cadena |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | Etiqueta del entorno adjunta a la telemetría exportada. | — | Cadena |
| `OTEL_INSECURE_EXPORTER` | Permite una conexión OTLP en texto plano. Déjala en `false` en producción. | `false` | `true`, `false` |
## Autenticación de plugins
Los servicios de Lerian pueden autenticar las rutas protegidas —incluida la API de administración de Systemplane— a través de Access Manager (respaldado por Casdoor). El toggle de autenticación, su nombre de variable y su valor por defecto difieren según el servicio: la mayoría de los plugins y productos usan `PLUGIN_AUTH_ENABLED` (por defecto `false`, desactivado), mientras que los rails nativos como SILOC y SPB usan `AUTH_ENABLED` (por defecto `true`, activado —obligatorio en producción y SaaS) junto con `AUTH_ADDRESS`. Activa siempre la autenticación en producción y consulta la página de variables de entorno de cada producto o rail para conocer el nombre del toggle, su valor por defecto y las rutas que protege.
| Variable | Descripción | Valor por defecto | Valores permitidos |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ------------------ |
| `PLUGIN_AUTH_ENABLED` / `AUTH_ENABLED` | Exige autenticación de Access Manager en las rutas protegidas. El nombre y el valor por defecto varían según el servicio: los plugins usan `PLUGIN_AUTH_ENABLED`, los rails nativos usan `AUTH_ENABLED`. | Plugins `false`, rails `true` | `true`, `false` |
| `PLUGIN_AUTH_ADDRESS` / `PLUGIN_AUTH_HOST` / `AUTH_ADDRESS` | Dirección del servicio Access Manager. Obligatoria cuando está habilitada. | — | Dirección |
## Variables por producto
Las variables anteriores son la base compartida. Cada producto añade las suyas: prefijos de almacenes de datos, URL de integración, ajuste de workers y toggles de funcionalidades. Usa las páginas por producto para la lista completa y actual:
La lista exhaustiva de variables por servicio se entrega en el archivo `.env.example` de cada servicio. Trátalo como la fuente de verdad para un release específico, y nunca incluyas valores secretos reales en él.