Fundamentos de configuración 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 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.

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

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 y Salud y 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 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

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

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.

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:

Midaz

Tracer

Reporter

Flowker

Lender

Fetcher

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.

Resumen

Fundamentos de integración

Estabilidad y calidad

Fundamentos de configuración BYOC

Modo de despliegue y TLS

Servidor

Almacenes de datos

Multi-tenancy

Configuración en tiempo de ejecución

Streaming y outbox

Descubrimiento de servicios

Observabilidad

Autenticación de plugins

Variables por producto

Midaz

Tracer

Reporter

Flowker

Lender

Fetcher

​Modo de despliegue y TLS

​Servidor

​Almacenes de datos

​Multi-tenancy

​Configuración en tiempo de ejecución

​Streaming y outbox

​Descubrimiento de servicios

​Observabilidad

​Autenticación de plugins

​Variables por producto

Midaz

Tracer

Reporter

Flowker

Lender

Fetcher

Modo de despliegue y TLS

Servidor

Almacenes de datos

Multi-tenancy

Configuración en tiempo de ejecución

Streaming y outbox

Descubrimiento de servicios

Observabilidad

Autenticación de plugins

Variables por producto