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

# Deploy e configuração

> Faça o deploy do JD Courier na sua infraestrutura com o chart Helm: os quatro papéis, as duas portas, as variáveis de ambiente e o comportamento da licença.

No BYOC, você faz o deploy do Courier no seu próprio cluster Kubernetes com o chart Helm dele. O chart roda uma imagem em quatro papéis, um deploy para cada papel. Na Lerian Cloud, a Lerian opera o Courier no [modo multi-tenant](#multi-tenant-mode).

## Antes de começar

***

Confirme que você tem estes itens:

* Um cluster Kubernetes e o Helm.
* Um banco de dados PostgreSQL para o Courier.
* O endereço do seu Access Manager.
* A sua chave de licença da Lerian e o ID da organização.
* As configurações do canal SPB que a JD deu à sua instituição.

## Os quatro papéis

***

Um binário carrega os quatro papéis. A variável `COURIER_ROLES` seleciona os papéis de um processo. Ela não tem padrão: um processo sem ela não inicia. O chart a define para cada deploy, e ele recusa um valor em `config`.

| Papel | Réplicas no chart | Porta do Service | O que serve |
| - | - | - | - |
| `spb-consumer` | Exatamente `1`, com a estratégia `Recreate` | Nenhuma | Lê as mensagens SPB da JD e as roteia. |
| `spb-sender` | `2` | `8081` | A interface SOAP para os motores. |
| `pix-ingress` | `2` | `8080` | O endereço para o qual a JD envia as chamadas Pix. |
| `admin` | `1` | `8080` | A API do operador, a API dos motores e a conciliação. |

Rode `spb-consumer` como exatamente uma réplica. Uma leitura da fila da JD remove a mensagem, então o consumidor é um escritor único. O chart se recusa a renderizar mais de uma réplica. Um processo que combina `spb-consumer` com outro papel para no boot com o código `JDC-0314`.

## Portas

***

| Porta | Variável | Padrão | Serve |
| - | - | - | - |
| HTTP | `SERVER_ADDRESS` | `:8080` | Os probes, a API do operador, a API dos motores e o endereço Pix. |
| SOAP | `SOAP_SERVER_ADDRESS` | `:8081` | A interface SOAP, apenas no papel `spb-sender`. |

O chart deriva as duas variáveis de `ports.http` e `ports.soap`. Cada papel responde aos probes na porta HTTP: `/health` para liveness, `/readyz` para readiness e `/version` para o build.

## Instalar com Helm

***

O chart é `oci://ghcr.io/lerianstudio/br-jd-courier-helm`. Leia as versões dele antes de fixar uma:

```bash theme={null}
helm show chart oci://ghcr.io/lerianstudio/br-jd-courier-helm
```

1. Crie o Secret que cada papel lê. O chart não o cria.

   Coloque `LICENSE_KEY`, `POSTGRES_PASSWORD`, `DATABASE_URL` e, no modo single-tenant, `JD_PASSWORD` em um Secret do Kubernetes que você cria. O chart recusa essas chaves nos valores de `config`.

2. Escreva o seu arquivo de valores. Coloque as variáveis que não são secretas em `config`. O chart as coloca em um ConfigMap que cada papel lê.

3. Instale o chart:

   ```bash theme={null}
   CHART_VERSION="paste-the-chart-version-here"
   helm install jd-courier oci://ghcr.io/lerianstudio/br-jd-courier-helm \
     --version "$CHART_VERSION" \
     -f values.yaml
   ```

Antes de cada instalação e upgrade, o chart roda um job que aplica as migrações do banco de dados. O Courier não aplica migrações no boot.

## Variáveis de ambiente

***

Esta seção lista as variáveis do Courier. Para as variáveis de banco de dados, multi-tenant, telemetria e autenticação que cada serviço da Lerian compartilha, veja [Essenciais de configuração BYOC](/pt/reference/byoc-configuration).

<Note>
  Nas tabelas abaixo, a coluna **Padrão / Obrigatória** mostra o valor padrão. **Obrigatória** marca as variáveis que você deve definir. `—` significa sem padrão. `🔒` marca um segredo.
</Note>

### Serviço

| Variável | Padrão / Obrigatória | Descrição |
| - | - | - |
| `COURIER_ROLES` | **Obrigatória** | Os papéis do processo, separados por vírgulas: `spb-consumer`, `spb-sender`, `pix-ingress`, `admin`. O chart a define. |
| `ENVIRONMENT_NAME` | `development` | O ambiente. Defina `production` em produção: então, o Courier aplica as verificações de produção no boot. |
| `DEPLOYMENT_MODE` | `local` | `byoc`, `saas` ou `local`. Outro valor para o boot. |
| `HTTP_BODY_LIMIT_BYTES` | `1048576` | O maior corpo de requisição na porta HTTP. |
| `POSTGRES_SSLMODE` | `disable` | Com `disable`, o Courier não inicia, a menos que `ALLOW_INSECURE_TLS=true`. Use `verify-full` em produção. |

### Canal SPB da JD

Os dois papéis SPB leem estas variáveis.

| Variável | Padrão / Obrigatória | Descrição |
| - | - | - |
| `JD_BASE_URL` | **Obrigatória** em produção | O endereço do serviço SPB da JD. |
| `JD_SOAP_PATH` | `/soap` | O caminho do serviço SOAP da JD. |
| `JD_LEGACY_CODE` | **Obrigatória** em produção | Veja a nota abaixo. |
| `JD_USER_CODE` | **Obrigatória** em produção | Veja a nota abaixo. |
| `JD_PASSWORD` | 🔒 **Obrigatória** em produção | Veja a nota abaixo. |
| `SPB_VENDOR_TIMEOUT` | `7s` | Quanto tempo o Courier espera pela JD. Deve ser maior que zero e menor que `8s`. |

`JD_LEGACY_CODE`, `JD_USER_CODE` e `JD_PASSWORD` são as credenciais JD que você já tem (até 10, 10 e 20 caracteres). Em produção, use https em `JD_BASE_URL`.

### Interface SOAP

O papel `spb-sender` lê estas variáveis.

| Variável | Padrão / Obrigatória | Descrição |
| - | - | - |
| `SOAP_MAX_BODY_BYTES` | `10485760` | O maior corpo de requisição SOAP. |
| `SPB_CHANNEL_CREDENTIAL_ROTATION_OVERLAP` | `24h` | Veja a nota abaixo. |
| `SOAP_TLS_CERT_FILE` | — | Veja a nota abaixo. |
| `SOAP_TLS_KEY_FILE` | — | Veja a nota abaixo. |
| `SOAP_TLS_TERMINATED_UPSTREAM` | `false` | Veja a nota abaixo. |

Em produção, dê ao `spb-sender` um certificado e uma chave TLS (`SOAP_TLS_CERT_FILE`, `SOAP_TLS_KEY_FILE`), ou defina `SOAP_TLS_TERMINATED_UPSTREAM` quando o TLS termina antes do Courier. A versão mínima do TLS é 1.2.

### Pix

| Variável | Padrão / Obrigatória | Descrição |
| - | - | - |
| `PIX_VENDOR_SUBJECTS` | **Obrigatória** para `pix-ingress` | Veja a nota abaixo. |
| `AWS_REGION` | `us-east-1` | A região AWS do AWS Secrets Manager. |

`PIX_VENDOR_SUBJECTS` lista as identidades da JD que podem chamar o `pix-ingress`. O Courier recusa todos os outros chamadores, inclusive os motores.

O Courier lê o client ID e o secret de cada motor no AWS Secrets Manager, em `AWS_REGION`. Guarde-os lá antes de registrar o motor. Sem acesso ao AWS Secrets Manager, o Courier mantém as mensagens Pix do motor e não as entrega.

Guarde o secret de cada motor em `tenants/{ENVIRONMENT_NAME}/{tenantId}/jd-courier/external/pix-engine-{engineId}/credentials/versions/{versionId}`. `pixDelivery.credentialRef` deve apontar para esse secret. O Courier não entrega ao motor quando a referência aponta para qualquer outro caminho. O secret é um objeto JSON com os campos `clientId` e `clientSecret`. `{versionId}` é um UUID em minúsculas. No modo single-tenant, `{tenantId}` é o ID do tenant do canal Pix ativo do Courier.

### Licença

| Variável | Padrão / Obrigatória | Descrição |
| - | - | - |
| `LICENSE_KEY` | 🔒 **Obrigatória** | A sua chave de licença da Lerian. |
| `ORGANIZATION_IDS` | — | O ID da sua organização. |
| `APPLICATION_NAME` | `jd-courier` | O nome da aplicação que a verificação da licença usa. |

## Comportamento da licença

***

O Courier verifica a licença no boot. Não reinicie um pod enquanto a licença não for válida: o pod não inicia até você corrigir a licença.

Enquanto o processo roda, o Courier verifica a licença de novo a cada 6 horas. Quando a licença fica revogada, o processo continua no ar:

* A API do operador e a API dos motores respondem `503 JDC-0902`.
* O endereço Pix e a interface SOAP respondem `503`.
* O papel `spb-consumer` para de ler da JD.

O probe `/readyz` informa o estado da licença. Enquanto a licença está revogada, o Courier a verifica de novo depois de 1 minuto, e o intervalo dobra até 15 minutos. Na primeira resposta válida, o Courier volta a servir sem reinício.

<h2 id="multi-tenant-mode">
  Modo multi-tenant
</h2>

***

O modo multi-tenant permite que um deploy do Courier atenda mais de um cliente. A Lerian Cloud roda o Courier nesse modo, e a Lerian opera o deploy. As outras seções desta página descrevem um deploy single-tenant.

`MULTI_TENANT_ENABLED=true` liga o modo. Para as outras variáveis `MULTI_TENANT_*`, veja [Essenciais de configuração BYOC](/pt/reference/byoc-configuration) e [Multi-tenancy](/pt/platform/multi-tenancy).

No [modo multi-tenant](/pt/platform/multi-tenancy), a API do operador, a API dos motores e o Pix ingress obtêm o tenant do token verificado de quem chama. O endereço SOAP obtém o tenant da credencial de canal.

### O que muda em relação ao single-tenant

* O papel `spb-consumer` continua rodando como exatamente uma réplica. Ele lê da JD para cada tenant que tem um canal SPB ativo.
* O papel `spb-consumer` lê a lista de tenants de novo a cada 30 segundos (`SPB_TENANT_REFRESH_SEC`). Quando o banco de dados de um tenant não responde, o papel pula esse tenant nessa passada. Os outros tenants continuam.
* A conciliação roda um ciclo para cada tenant e trilho.
* O papel `pix-ingress` exige `SYSTEMPLANE_ENABLED=true`. Sem ela, o processo não inicia.
* O chart não roda o job de migrações. Defina `migrations.enabled=false`: o chart se recusa a renderizar o job nesse modo. Aplique as migrações de cada tenant pelo Tenant Manager.

No modo multi-tenant, o Courier ignora `JD_BASE_URL`, `JD_SOAP_PATH`, `JD_LEGACY_CODE`, `JD_USER_CODE` e `JD_PASSWORD`. Ele lê o endereço JD e a credencial JD de cada tenant no AWS Secrets Manager.

No modo multi-tenant, o Courier ignora `PIX_VENDOR_SUBJECTS`. A chave de configuração em runtime `jd-courier.pix/vendor_subjects` lista as identidades da JD de cada tenant. O Courier responde 503 a todas as chamadas Pix da JD para um tenant sem entrada.

No modo multi-tenant, o Courier não inicia com `PLUGIN_AUTH_ENABLED=false`. Coloque `MULTI_TENANT_SERVICE_API_KEY` e `MULTI_TENANT_REDIS_PASSWORD` no Secret do Kubernetes.

### Quem configura o quê na Lerian Cloud

* A **Lerian** configura o deploy: as variáveis de ambiente, a configuração em runtime e as migrações de cada tenant.
* O **seu operador** usa a API do operador como em um deploy single-tenant: os motores, o mapa de titularidade, os modos de entrega, o bypass, as mensagens retidas e a conciliação.
* Os **seus motores** usam a API dos motores, a interface SOAP e o endereço Pix como em um deploy single-tenant.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.