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

> Las variables de entorno compartidas entre los servicios Go de Lerian, con sus valores posibles: los ajustes de base que un operador define al desplegar en su propia infraestructura en la nube o en las instalaciones (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.

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

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

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

## 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. Algunos servicios activan controles de seguridad más estrictos cuando se define como `production`.                            | `development`      | Cadena libre                     |
| `VERSION`        | Etiqueta de versión del servicio expuesta por `/version`.                                                                                           | Por release        | Cadena semver                    |

<Note>
  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).
</Note>

## 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 CA PEM codificado en base64.                                                                                                                                                                                                                                  | `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).                                                                                                                                                                                                                                                  | —                 | Cadena / secreto                                 |

<Note>
  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).
</Note>

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

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

## 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 todos los servicios excepto en el worker de Fetcher, que define `STREAMING_ENABLED=true` para emitir eventos de finalización de trabajos.

| Variable                  | Descripción                                                                                  | Valor por defecto                   | Valores permitidos                      |
| ------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------- | --------------------------------------- |
| `STREAMING_ENABLED`       | Habilita el productor de eventos.                                                            | `false` (worker de Fetcher: `true`) | `true`, `false`                         |
| `STREAMING_BROKERS`       | Brokers de arranque de Kafka/RedPanda, como una lista `host:port` separada por comas.        | —                                   | CSV de `host:port`                      |
| `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`                         |

<Note>
  `STREAMING_SASL_*` y `STREAMING_TLS_*` aseguran la conexión al broker: defínelas cuando tu broker requiera autenticación o TLS.
</Note>

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

<Note>
  Algunos servicios usan alias heredados (`SD_ADVERTISE_*`, `CONSUL_ADDR`) para el mismo comportamiento.
</Note>

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

<CardGroup cols={2}>
  <Card title="Midaz" href="/es/midaz/midaz-environment-variables" />

  <Card title="Tracer" href="/es/tracer/tracer-environment-variables" />

  <Card title="Reporter" href="/es/reporter/reporter-environment-variables" />

  <Card title="Flowker" href="/es/flowker/flowker-environment-variables" />

  <Card title="Lender" href="/es/lender/configuration-and-deploy" />

  <Card title="Fetcher" href="/es/fetcher/fetcher-configuration" />
</CardGroup>

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