Aspectos esenciales de la configuración de BYOC

Variables de entorno compartidas entre los servicios de Lerian en Go: el eje común que los operadores configuran para todo el despliegue al ejecutar BYOC en su propia nube o on-premise.

En un despliegue BYOC (bring your own cloud), ejecutas los productos de Lerian dentro de tu propia infraestructura de AWS, GCP u on-premise. Tú eres dueño de los datos y del runtime. Configuras cada servicio mediante variables de entorno, y la mayoría son específicas del servicio. Esta página cubre el eje común: las variables que se comportan igual en todos los servicios de Lerian en Go. Configura una vez los parámetros que aplican a todo el despliegue y usa la página propia de cada producto para el resto.

Para Pix Lerian v1.0.0, la configuración BYOC admite los componentes entregados y la vía de integración/pruebas con el adaptador simulado. No hace disponible el conector de mensajería nativa de SPI ni convierte el adaptador simulado en un riel de producción.

Estas variables forman el eje común, no la lista completa. Los prefijos de las variables difieren un poco entre servicios (por ejemplo, un servicio con bases de datos separadas para onboarding y transacciones las organiza con espacios de nombres distintos), y cada servicio agrega sus propias claves. Consulta Variables por producto para ver las listas completas.

​

Modo de despliegue y TLS

DEPLOYMENT_MODE define con qué rigor el servicio exige TLS en sus conexiones de infraestructura. La respuesta de /readyz informa su valor.

Variable	Descripción	Predeterminado	Valores permitidos
DEPLOYMENT_MODE	Postura de exigencia de TLS. local permite conexiones en texto plano. byoc recomienda TLS y advierte ante texto plano, pero igual arranca. saas exige TLS de forma obligatoria: el servicio no arranca si alguna conexión con una dependencia carece de TLS.	local	local, byoc, saas
ALLOW_INSECURE_TLS	Omite la exigencia de TLS por conexión en los DSN de infraestructura. Pensado solo para desarrollo local.	false	true, false

Para un despliegue BYOC en producción, configura DEPLOYMENT_MODE=byoc, conecta cada almacén de datos por TLS y deja ALLOW_INSECURE_TLS sin definir (false). Los valores predeterminados de local traen conexiones en texto plano y no son seguros para producción.

​

Servidor

Variable	Descripción	Predeterminado	Valores permitidos
SERVER_ADDRESS	Dirección de escucha HTTP principal (host:port, normalmente :port). Los sondeos de liveness, readiness y versión se enlazan a este mismo puerto.	Varía según el servicio	host:port
LOG_LEVEL	Nivel de detalle del log. Usa info o superior en producción.	debug	debug, info, warn, error
ENV_NAME	Etiqueta de entorno. En SLC, se normaliza a una lista de valores permitidos.	development	SLC: production, staging, uat, development, local
VERSION	Etiqueta de versión del servicio expuesta por /version.	Según la versión	Cadena semver

Algunos servicios exponen un SERVER_PORT numérico en lugar de SERVER_ADDRESS, o junto con esta. Los componentes worker sin una API HTTP principal exponen un puerto de salud dedicado (por ejemplo, HEALTH_PORT o WORKER_SERVER_PORT). Consulta Puertos de red predeterminados y Salud y readiness.

​

Almacenes de datos

Todo 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 siguiente tabla muestra la forma común. Consulta la página de cada producto para conocer los nombres exactos.

Variable	Descripción	Predeterminado	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 y nunca la subas al repositorio.	—	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 Indirect); Midaz la organiza por base de datos lógica como DB_{MODULE}_NAME. Consulta la página de cada producto.	—	Cadena
POSTGRES_SSLMODE	Modo de TLS de libpq. Usa require o un nivel más estricto en producción.	disable	disable, require, verify-ca, verify-full
POSTGRES_REPLICA_*	Conexión opcional de réplica de lectura (misma forma que la principal).	—	Host / puerto / credenciales
MONGO_URI / MONGO_HOST / MONGO_PORT	Conexión a MongoDB, como URI completa o como host y puerto por separado.	—	Cadena de conexión / host / puerto
MONGO_TLS_CA_CERT	Certificado CA en PEM codificado en Base64 para TLS (por ejemplo, un servicio de MongoDB administrado).	—	Base64 PEM
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 en PEM codificado en Base64. En SLC, REDIS_TLS=true requiere que REDIS_CA_CERT no esté vacío.	false / —	true, false / base64 PEM
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 principales suelen organizar las conexiones por base de datos lógica (por ejemplo, DB_ONBOARDING_*, DB_TRANSACTION_*, MONGO_CRM_*). Los plugins y los rieles usan la forma plana POSTGRES_* de arriba. En modo multi-tenant, el servicio ignora las credenciales estáticas de almacenamiento y resuelve las conexiones por tenant (ver más abajo).

​

Multi-tenancy

Multi-tenancy está deshabilitado de forma predeterminada. Cuando lo habilitas, cada conexión de almacenamiento de datos pasa de la configuración estática a la resolución por tenant a través de Tenant Manager. El servicio también agrega un sondeo de readiness por tenant en GET /readyz/tenant/{id}.

Variable	Descripción	Predeterminado	Valores permitidos
MULTI_TENANT_ENABLED	Habilita la resolución de conexión por tenant. Cuando es false, el servicio funciona en modo single-tenant con las conexiones estáticas descritas arriba.	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 texto plano (http://). Nunca la habilites en producción: las credenciales viajan sin cifrar.	false	true, false
MULTI_TENANT_REDIS_HOST / MULTI_TENANT_REDIS_PORT	Endpoint opcional de Redis para eventos del ciclo de vida del tenant (descubrimiento orientado a eventos).	— / 6379	Host / puerto

Existen parámetros adicionales por servicio para el tamaño del pool por tenant, el circuit breaker y el TTL de la caché (MULTI_TENANT_MAX_TENANT_POOLS, MULTI_TENANT_CIRCUIT_BREAKER_*, MULTI_TENANT_CACHE_TTL_SEC, entre otros). Consulta las páginas de cada producto.

​

Configuración de runtime

Variable	Descripción	Predeterminado	Valores permitidos
SYSTEMPLANE_ENABLED	Habilita la API de administración de configuración en tiempo de ejecución de systemplane en el puerto principal. Está deshabilitada de forma predeterminada en la mayoría de los servicios; algunos, como SPI, la habilitan de forma predeterminada. 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 conocer la API, los espacios de nombres y los permisos requeridos.

​

Streaming y outbox

La vía de publicación de eventos (un productor de lib-streaming respaldado por un outbox transaccional) está deshabilitada de forma predeterminada en la mayoría de los servicios. La excepción son los rieles nativos (por ejemplo, SPI y SILOC), que no exponen STREAMING_ENABLED en absoluto. En esos rieles, el streaming no tiene modo deshabilitado: STREAMING_BROKERS es obligatoria, y el servicio se niega a iniciar cuando ese valor falta o no es válido. Consulta la página de cada producto para conocer su contrato.

Variable	Descripción	Predeterminado	Valores permitidos
STREAMING_ENABLED	Habilita el productor de eventos, en los servicios que exponen este interruptor. Los rieles nativos no leen esta variable: su streaming siempre está activo.	false	true, false
STREAMING_BROKERS	Brokers de arranque de Kafka/RedPanda, como una lista de host:port separada por comas. Obligatoria al iniciar en los servicios cuyo streaming no tiene modo deshabilitado.	—	host:port CSV
STREAMING_CLOUDEVENTS_SOURCE	El source de CloudEvents que se graba en cada evento que emite el servicio. No tiene valor predeterminado: un productor que transmite a un broker con este valor vacío se detiene al iniciar. Varios productos aceptan exactamente un literal y se niegan a arrancar con cualquier otro, así que toma el valor de la página propia del producto.	—	El literal que exige el producto
STREAMING_EVENT_POLICIES	Anulaciones de política de entrega por evento, como entradas event.key.attribute=value separadas por comas, punto y coma o saltos de línea (por ejemplo transaction.created.enabled=true,transaction.created.outbox=always). Los atributos son enabled, direct, outbox y dlq. Si se deja vacío, se conserva la política predeterminada de cada evento.	—	Lista event.key.attribute=value
STREAMING_COMPRESSION	Códec de compresión del productor.	lz4	none, gzip, snappy, lz4, zstd
STREAMING_REQUIRED_ACKS	Nivel de confirmación (ack) del productor.	all	all, leader, none
OUTBOX_ENABLED	Habilita el despachador del outbox transaccional (donde el servicio lo expone por separado).	false	true, false

STREAMING_SASL_* y STREAMING_TLS_* protegen la conexión con el broker. Configúralas cuando tu broker exija autenticación o TLS.

​

Descubrimiento de servicios

El descubrimiento de servicios con Consul está deshabilitado de forma predeterminada. Cuando está habilitado, el servicio se registra a sí mismo y resuelve a sus pares a través de Consul en lugar de usar direcciones estáticas.

Variable	Descripción	Predeterminado	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 funciona por envío (push, OTLP). Algunos servicios también exponen un endpoint /metrics para el scraping de Prometheus. Consulta Salud y readiness.

Variable	Descripción	Predeterminado	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, cuando se usa un host y puerto por separado.	4317	Puerto
OTEL_RESOURCE_SERVICE_NAME	Nombre del servicio adjunto a la telemetría exportada.	Predeterminado del servicio	Cadena
OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT	Etiqueta de 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 rutas protegidas, incluida la API de administración de systemplane, a través de Access Manager (respaldado por Caradhras). El interruptor de autenticación, el nombre de su variable y su valor predeterminado varían según el servicio. La mayoría de los plugins y productos usan PLUGIN_AUTH_ENABLED (predeterminado false, deshabilitado). Los rieles nativos como SILOC y SPB usan AUTH_ENABLED (predeterminado true, habilitado, obligatorio en producción y en SaaS) junto con AUTH_ADDRESS. Habilita siempre la autenticación en producción. Consulta la página de variables de entorno propia de cada producto o riel para conocer el nombre autoritativo del interruptor, su valor predeterminado y las rutas que protege.

Variable	Descripción	Predeterminado	Valores permitidos
PLUGIN_AUTH_ENABLED / AUTH_ENABLED	Exige la autenticación de Access Manager en las rutas protegidas. El nombre y el valor predeterminado varían según el servicio: los plugins usan PLUGIN_AUTH_ENABLED y los rieles nativos usan AUTH_ENABLED.	Plugins false, rieles true	true, false
PLUGIN_AUTH_ADDRESS / PLUGIN_AUTH_HOST / AUTH_ADDRESS	Dirección del servicio de Access Manager. Obligatoria cuando está habilitado.	—	Dirección

​

Variables por producto

Las variables anteriores forman la base común. Cada producto agrega las suyas: prefijos de almacenamiento de datos, URLs de integración, ajustes de workers e interruptores de funcionalidad. Usa las páginas de cada producto para ver la lista completa y actualizada:

Midaz

Tracer

Reporter

Flowker

Lender

La lista exhaustiva de variables por servicio se distribuye en el archivo .env.example de cada servicio. Trátalo como la fuente de verdad para una versión específica y nunca subas valores reales de secretos en él.