COURIER_ROLES.
Nas tabelas, a coluna Obrigatória marca uma variável que você deve definir, sempre ou na condição indicada. — significa sem padrão. 🔒 marca um segredo: guarde-o no seu cofre de segredos.
Com
ENVIRONMENT_NAME=production, o Courier não inicia a menos que tudo isto seja verdade: PLUGIN_AUTH_ENABLED é true, POSTGRES_PASSWORD está definida, POSTGRES_SSLMODE não é disable e ALLOW_CORS_WILDCARD não é true. Cada papel acrescenta as próprias verificações, indicadas nas tabelas abaixo.Serviço e servidor
| Variável | Descrição | Padrão | Obrigatória |
|---|---|---|---|
COURIER_ROLES | Os papéis do processo, separados por vírgulas: spb-consumer, spb-sender, pix-ingress, admin. Um papel desconhecido ou repetido para o boot. spb-consumer roda sozinho no processo dele. | — | Sim |
ENVIRONMENT_NAME | O ambiente. production liga as verificações de produção. ENV_NAME é lida quando ENVIRONMENT_NAME não está definida. | development | Não |
DEPLOYMENT_MODE | byoc, saas ou local. Outro valor para o boot. | local | Não |
LOG_LEVEL | O nível de log. | info | Não |
SERVER_ADDRESS | A porta HTTP: os probes, a API do operador, a API dos motores e o endereço Pix. | :8080 | Não |
SERVER_TLS_CERT_FILE, SERVER_TLS_KEY_FILE | O certificado e a chave para TLS na porta HTTP. Defina as duas ou nenhuma. Um processo com spb-sender ou com o trânsito Pix as recusa, a menos que TLS_TERMINATED_UPSTREAM seja true. | — | Não |
TLS_TERMINATED_UPSTREAM | true quando o TLS termina antes da porta HTTP. | false | Não |
HTTP_BODY_LIMIT_BYTES | O maior corpo de requisição na porta HTTP, em bytes. | 1048576 | Não |
SWAGGER_ENABLED | Serve o documento OpenAPI na raiz da porta HTTP. O Courier a ignora em produção. | false | Não |
SYSTEMPLANE_ENABLED | Liga as configurações de runtime e a API delas em /system. | false | Não |
INFRA_CONNECT_TIMEOUT_SEC | O limite de tempo para conectar aos datastores no boot, em segundos. | 30 | Não |
IDEMPOTENCY_RETRY_WINDOW_SEC | Por quanto tempo o Courier guarda a resposta a uma chave X-Idempotency, em segundos. | 300 | Não |
ALLOW_CORS_WILDCARD | A produção recusa true. | — | Não |
PostgreSQL
| Variável | Descrição | Padrão | Obrigatória |
|---|---|---|---|
POSTGRES_HOST | O host primário. | localhost | Não |
POSTGRES_PORT | A porta primária. | 5432 | Não |
POSTGRES_USER | O usuário do banco de dados. | jd-courier | Não |
POSTGRES_PASSWORD | 🔒 A senha do banco de dados. | — | Em produção |
POSTGRES_NAME | O nome do banco de dados. | jd-courier | Não |
POSTGRES_SSLMODE | O modo TLS da libpq. Com disable, o Courier não inicia, a menos que ALLOW_INSECURE_TLS seja true. A produção recusa disable. Use verify-full em produção. | require | Não |
POSTGRES_REPLICA_HOST, POSTGRES_REPLICA_PORT, POSTGRES_REPLICA_USER, POSTGRES_REPLICA_PASSWORD, POSTGRES_REPLICA_NAME, POSTGRES_REPLICA_SSLMODE | Uma réplica de leitura opcional. Um valor que você não define recebe o valor do primário. Quando você define qualquer uma delas, POSTGRES_REPLICA_HOST é obrigatória. A produção recusa POSTGRES_REPLICA_SSLMODE=disable. | — | Não |
POSTGRES_MAX_OPEN_CONNS | O maior número de conexões abertas. | 25 | Não |
POSTGRES_MAX_IDLE_CONNS | O maior número de conexões ociosas. | 5 | Não |
POSTGRES_CONN_MAX_LIFETIME_MINS | A maior duração de uma conexão, em minutos. | 30 | Não |
POSTGRES_CONN_MAX_IDLE_TIME_MINS | O maior tempo ocioso de uma conexão, em minutos. | 5 | Não |
POSTGRES_CONNECT_TIMEOUT_SEC | O limite de tempo para abrir uma conexão, em segundos. | 10 | Não |
ALLOW_INSECURE_TLS | true permite que as conexões aos datastores funcionem sem TLS. | false | Não |
Access Manager
| Variável | Descrição | Padrão | Obrigatória |
|---|---|---|---|
PLUGIN_AUTH_ENABLED | Verifica o token e a permissão do Access Manager em cada chamada. false precisa de ALLOW_AUTH_DISABLED_LOCAL_ONLY=true. A produção e o modo multi-tenant recusam false. | true | Não |
PLUGIN_AUTH_HOST | O endereço do seu Access Manager. | — | Quando PLUGIN_AUTH_ENABLED é true |
ALLOW_AUTH_DISABLED_LOCAL_ONLY | Permite que PLUGIN_AUTH_ENABLED=false inicie, apenas na máquina de um desenvolvedor. | false | Não |
AUTH_M2M_INVERSION_ENABLED | Vincula cada chamada de motor à identidade que o Access Manager verificou. Com false, o Courier recusa cada credencial de motor com 401, e um processo de produção com o papel admin não inicia. | true | Não |
AUTH_M2M_PRODUCT_FORWARD_ENABLED | Envia o nome de produto do Courier ao Access Manager quando ele autoriza uma chamada de motor. | true | Não |
AUTH_TIMEOUT, AUTH_CACHE_TTL, AUTH_RETRY_MAX, AUTH_BREAKER_ENABLED, AUTH_REQUIRED, AUTH_PRINCIPAL_REQUIRED_WHEN_DISABLED, AUTH_JWT_VERIFY_CERT, AUTH_JWT_VERIFY_CERT_PATH, AUTH_JWT_ISSUER | As configurações do cliente do Access Manager. Um valor que não é válido para o boot. | Os padrões do cliente | Não |
IDP_DECLARATION_ENABLED | No modo single-tenant, true publica no seu Access Manager as permissões do Courier e a adesão dele a parceiros. Sem valor ou false, publica apenas a adesão a parceiros. | — | Não |
IDP_HOST | O endereço do serviço de identidade do Access Manager, onde o Courier as publica. | — | Para a publicação |
IDP_M2M_CLIENT_ID | O client ID da aplicação que as publica. | — | Para a publicação |
IDP_M2M_CLIENT_SECRET | 🔒 O secret dessa aplicação. | — | Para a publicação |
Canal SPB da JD
Os papéisspb-consumer e spb-sender leem estas variáveis.
| Variável | Descrição | Padrão | Obrigatória |
|---|---|---|---|
JD_BASE_URL | O endereço do serviço SPB da JD. Use https em produção. | — | Em produção, no modo single-tenant |
JD_SOAP_PATH | O caminho do serviço SOAP da JD. | /soap | Não |
JD_LEGACY_CODE | A credencial JD que você já tem. No máximo 10 bytes. | — | Em produção, no modo single-tenant |
JD_USER_CODE | A credencial JD que você já tem. No máximo 10 bytes. | — | Em produção, no modo single-tenant |
JD_PASSWORD | 🔒 A credencial JD que você já tem. No máximo 20 bytes. | — | Em produção, no modo single-tenant |
SPB_VENDOR_TIMEOUT | Quanto tempo o Courier espera pela JD. Deve ser maior que zero e menor que 8s. | 7s | Não |
JD_ALLOW_PRIVATE_NETWORK | true permite que o Courier se conecte à JD em um endereço de rede privada, para o canal SPB e a cabine SPI. A produção a aceita. | false | Não |
JD_PRIVATE_KEY_PEM | Não deve estar presente em produção. O Courier não assina nada. | — | Não |
Interface SOAP
O papelspb-sender lê estas variáveis.
| Variável | Descrição | Padrão | Obrigatória |
|---|---|---|---|
SOAP_SERVER_ADDRESS | A porta SOAP. | :8081 | Não |
SOAP_MAX_BODY_BYTES | O maior corpo de requisição SOAP, em bytes. | 10485760 | Não |
SOAP_TLS_CERT_FILE, SOAP_TLS_KEY_FILE | O certificado e a chave para TLS na porta SOAP. Defina as duas ou nenhuma. A versão mínima do TLS é 1.2. | — | Em produção, a menos que SOAP_TLS_TERMINATED_UPSTREAM seja true |
SOAP_TLS_TERMINATED_UPSTREAM | true quando o TLS termina antes da porta SOAP. | false | Não |
SPB_CHANNEL_CREDENTIAL_ROTATION_OVERLAP | Por quanto tempo as credenciais SOAP e do trânsito Pix anteriores de um motor continuam funcionando depois que o operador emite uma nova. O papel admin a lê quando emite uma credencial. spb-sender recusa um valor que não é positivo. | 24h | Não |
Trânsito Pix
O papeladmin lê estas variáveis.
| Variável | Descrição | Padrão | Obrigatória |
|---|---|---|---|
PIX_TRANSIT_SERVER_ADDRESS | O endereço do trânsito Pix. Quando está vazio, o Courier não serve trânsito. | — | Para o trânsito |
PIX_TRANSIT_TLS_CERT_FILE, PIX_TRANSIT_TLS_KEY_FILE | O certificado e a chave para TLS no trânsito. Defina as duas ou nenhuma. A versão mínima do TLS é 1.2. | — | Em produção, a menos que PIX_TRANSIT_TLS_TERMINATED_UPSTREAM seja true |
PIX_TRANSIT_TLS_TERMINATED_UPSTREAM | true quando o TLS termina antes do trânsito. | false | Não |
JD_SPI_BASE_URL | No modo single-tenant, o endereço da cabine SPI da JD. Use https em produção. | — | Para o trânsito |
JD_SPI_CLIENT_ID | No modo single-tenant, o client ID da credencial da cabine SPI da sua instituição. | — | Para o trânsito |
JD_SPI_CLIENT_SECRET | 🔒 No modo single-tenant, o secret dessa credencial. | — | Para o trânsito |
JD_SPI_USE_SERVICE_SEGMENTS | true quando a JD serve a cabine SPI pelos caminhos do gateway dela: o Courier então pede o token em /auth e envia os resultados das validações de conta em /spi-api. | false | Não |
Drenagem do SPB
O papelspb-consumer lê estas variáveis. SPB_TAKE_BUDGET_SEC mais o maior entre SPB_IDLE_INTERVAL_SEC e SPB_EMPTY_BACKOFF_CAP_SEC deve ficar abaixo de SPB_LEASE_TTL_SEC.
| Variável | Descrição | Padrão | Obrigatória |
|---|---|---|---|
POD_NAME | O nome do detentor do lease de leitura. Quando está vazio, o Courier usa o nome do host. | — | Não |
SPB_LEASE_TTL_SEC | Quanto tempo o lease de leitura dura sem uma renovação, em segundos. | 30 | Não |
SPB_TAKE_BUDGET_SEC | O maior tempo para tirar uma mensagem da JD, em segundos. Deve ser pelo menos SPB_VENDOR_TIMEOUT. | 15 | Não |
SPB_IDLE_INTERVAL_SEC | A espera enquanto a drenagem não lê, em segundos. | 5 | Não |
SPB_EMPTY_BACKOFF_CAP_SEC | A maior espera depois que a JD informa uma fila vazia, em segundos. | 10 | Não |
SPB_PERSIST_TIMEOUT_SEC | O limite de tempo de uma tentativa de guardar uma mensagem, em segundos. | 60 | Não |
SPB_TENANT_REFRESH_SEC | Com que frequência a drenagem lê de novo a lista de tenants, em segundos. | 30 | Não |
SPB_MESSAGE_SIZE_ALERT_BYTES | Uma mensagem maior que isto grava um aviso. O Courier a guarda. | 1048576 | Não |
Pix e credenciais dos motores
| Variável | Descrição | Padrão | Obrigatória |
|---|---|---|---|
AWS_REGION | A região AWS do AWS Secrets Manager, onde o Courier lê as credenciais que usa nos motores. | us-east-1 | Não |
Licença
| Variável | Descrição | Padrão | Obrigatória |
|---|---|---|---|
LICENSE_KEY | 🔒 A sua chave de licença da Lerian. | — | Sim |
ORGANIZATION_IDS | O ID da sua organização. | — | Não |
APPLICATION_NAME | O nome de produto que a verificação da licença usa. Deixe-a sem valor: então, o Courier usa o próprio nome de produto. | — | Não |
Multi-tenancy
| Variável | Descrição | Padrão | Obrigatória |
|---|---|---|---|
MULTI_TENANT_ENABLED | Liga o modo multi-tenant. | false | Não |
MULTI_TENANT_URL | O endereço do Tenant Manager. | — | No modo multi-tenant |
MULTI_TENANT_SERVICE_API_KEY | 🔒 A chave do Courier no Tenant Manager. | — | No modo multi-tenant |
MULTI_TENANT_REDIS_HOST | O host Redis do cache de tenants. | — | No modo multi-tenant |
MULTI_TENANT_REDIS_PORT | A porta Redis. | 6379 | Não |
MULTI_TENANT_REDIS_PASSWORD | 🔒 A senha do Redis. | — | Não |
MULTI_TENANT_REDIS_TLS | Conecta ao Redis com TLS. | false | Não |
MULTI_TENANT_MAX_TENANT_POOLS | O maior número de pools de conexão de tenant. | 100 | Não |
MULTI_TENANT_IDLE_TIMEOUT_SEC | Por quanto tempo um pool de tenant ocioso fica aberto, em segundos. | 300 | Não |
MULTI_TENANT_TIMEOUT | O limite de tempo de uma chamada ao Tenant Manager, em segundos. | 30 | Não |
MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD | As falhas que abrem o circuit breaker do Tenant Manager. | 5 | Não |
MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC | Por quanto tempo o circuit breaker fica aberto, em segundos. | 30 | Não |
MULTI_TENANT_CACHE_TTL_SEC | Por quanto tempo o Courier guarda a configuração de um tenant, em segundos. | 120 | Não |
MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC | Com que frequência o Courier verifica as conexões de tenant, em segundos. | 30 | Não |
Telemetria
| Variável | Descrição | Padrão | Obrigatória |
|---|---|---|---|
ENABLE_TELEMETRY | Liga o OpenTelemetry. | true | Não |
OTEL_EXPORTER_OTLP_ENDPOINT | O endereço do coletor OTLP. | localhost:4317 | Não |
OTEL_RESOURCE_SERVICE_NAME | O nome do serviço na telemetria. | jd-courier | Não |
OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT | O nome do ambiente na telemetria. | development | Não |
OTEL_LIBRARY_NAME | O nome da biblioteca de instrumentação na telemetria. | O nome do módulo do Courier | Não |
OTEL_TRUST_INBOUND_TRACE_CONTEXT | Continua o trace que um chamador envia. Defina true apenas atrás de um gateway em que você confia. | false | Não |