> ## 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.
# Despliegue y configuración
> Despliega JD Courier en tu infraestructura con su chart de Helm: los cuatro roles, los dos puertos, las variables de entorno y el comportamiento de la licencia.
En BYOC, despliegas el Courier en tu propio clúster de Kubernetes con su chart de Helm. El chart ejecuta una imagen en cuatro roles, un despliegue para cada rol. En Lerian Cloud, Lerian opera el Courier en [modo multi-tenant](#multi-tenant-mode).
## Antes de empezar
***
Confirma que tienes estos elementos:
* Un clúster de Kubernetes y Helm.
* Una base de datos PostgreSQL para el Courier.
* La dirección de tu Access Manager.
* Tu clave de licencia de Lerian y el ID de la organización.
* La configuración del canal SPB que JD le dio a tu institución.
## Los cuatro roles
***
Un binario contiene los cuatro roles. La variable `COURIER_ROLES` selecciona los roles de un proceso. No tiene valor predeterminado: un proceso sin ella no arranca. El chart la define para cada despliegue, y rechaza un valor en `config`.
| Rol | Réplicas en el chart | Puerto del Service | Qué sirve |
| - | - | - | - |
| `spb-consumer` | Exactamente `1`, con la estrategia `Recreate` | Ninguno | Lee los mensajes SPB de JD y los enruta. |
| `spb-sender` | `2` | `8081` | La interfaz SOAP para los motores. |
| `pix-ingress` | `2` | `8080` | La dirección a la que JD envía las llamadas Pix. |
| `admin` | `1` | `8080` | La API del operador, la API de los motores y la conciliación. |
Ejecuta `spb-consumer` como exactamente una réplica. Una lectura de la cola de JD elimina el mensaje, así que el consumidor es un escritor único. El chart se niega a renderizar más de una réplica. Un proceso que combina `spb-consumer` con otro rol se detiene en el arranque con el código `JDC-0314`.
## Puertos
***
| Puerto | Variable | Predeterminado | Sirve |
| - | - | - | - |
| HTTP | `SERVER_ADDRESS` | `:8080` | Las sondas, la API del operador, la API de los motores y la dirección Pix. |
| SOAP | `SOAP_SERVER_ADDRESS` | `:8081` | La interfaz SOAP, solo en el rol `spb-sender`. |
El chart deriva las dos variables de `ports.http` y `ports.soap`. Cada rol responde a las sondas en el puerto HTTP: `/health` para liveness, `/readyz` para readiness y `/version` para el build.
## Instalar con Helm
***
El chart es `oci://ghcr.io/lerianstudio/br-jd-courier-helm`. Lee sus versiones antes de fijar una:
```bash theme={null}
helm show chart oci://ghcr.io/lerianstudio/br-jd-courier-helm
```
1. Crea el Secret que lee cada rol. El chart no lo crea.
Pon `LICENSE_KEY`, `POSTGRES_PASSWORD`, `DATABASE_URL` y, en el modo single-tenant, `JD_PASSWORD` en un Secret de Kubernetes que tú creas. El chart rechaza estas claves en sus valores de `config`.
2. Escribe tu archivo de valores. Pon las variables que no son secretas en `config`. El chart las pone en un ConfigMap que lee cada rol.
3. Instala el 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 instalación y actualización, el chart ejecuta un job que aplica las migraciones de la base de datos. El Courier no aplica migraciones en el arranque.
## Variables de entorno
***
Esta sección lista las variables del Courier. Para las variables de almacenamiento de datos, multi-tenancy, telemetría y autenticación que comparte cada servicio de Lerian, consulta [Aspectos esenciales de la configuración de BYOC](/es/reference/byoc-configuration).
En las tablas siguientes, la columna **Predeterminado / Obligatorio** muestra el valor predeterminado. **Obligatorio** marca las variables que debes definir. `—` significa sin valor predeterminado. `🔒` marca un secreto.
### Servicio
| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `COURIER_ROLES` | **Obligatorio** | Los roles del proceso, separados por comas: `spb-consumer`, `spb-sender`, `pix-ingress`, `admin`. El chart la define. |
| `ENVIRONMENT_NAME` | `development` | El entorno. Define `production` en producción: entonces, el Courier aplica sus verificaciones de producción en el arranque. |
| `DEPLOYMENT_MODE` | `local` | `byoc`, `saas` o `local`. Otro valor detiene el arranque. |
| `HTTP_BODY_LIMIT_BYTES` | `1048576` | El cuerpo de solicitud más grande en el puerto HTTP. |
| `POSTGRES_SSLMODE` | `disable` | Con `disable`, el Courier no arranca, a menos que `ALLOW_INSECURE_TLS=true`. Usa `verify-full` en producción. |
### Canal SPB de JD
Los dos roles SPB leen estas variables.
| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `JD_BASE_URL` | **Obligatorio** en producción | La dirección del servicio SPB de JD. |
| `JD_SOAP_PATH` | `/soap` | La ruta del servicio SOAP de JD. |
| `JD_LEGACY_CODE` | **Obligatorio** en producción | Consulta la nota siguiente. |
| `JD_USER_CODE` | **Obligatorio** en producción | Consulta la nota siguiente. |
| `JD_PASSWORD` | 🔒 **Obligatorio** en producción | Consulta la nota siguiente. |
| `SPB_VENDOR_TIMEOUT` | `7s` | Cuánto tiempo espera el Courier a JD. Debe ser mayor que cero y menor que `8s`. |
`JD_LEGACY_CODE`, `JD_USER_CODE` y `JD_PASSWORD` son las credenciales JD que ya tienes (hasta 10, 10 y 20 caracteres). En producción, usa https para `JD_BASE_URL`.
### Interfaz SOAP
El rol `spb-sender` lee estas variables.
| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `SOAP_MAX_BODY_BYTES` | `10485760` | El cuerpo de solicitud SOAP más grande. |
| `SPB_CHANNEL_CREDENTIAL_ROTATION_OVERLAP` | `24h` | Consulta la nota siguiente. |
| `SOAP_TLS_CERT_FILE` | — | Consulta la nota siguiente. |
| `SOAP_TLS_KEY_FILE` | — | Consulta la nota siguiente. |
| `SOAP_TLS_TERMINATED_UPSTREAM` | `false` | Consulta la nota siguiente. |
En producción, dale a `spb-sender` un certificado y una clave TLS (`SOAP_TLS_CERT_FILE`, `SOAP_TLS_KEY_FILE`), o define `SOAP_TLS_TERMINATED_UPSTREAM` cuando TLS termina antes del Courier. La versión mínima de TLS es 1.2.
### Pix
| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `PIX_VENDOR_SUBJECTS` | **Obligatorio** para `pix-ingress` | Consulta la nota siguiente. |
| `AWS_REGION` | `us-east-1` | La región de AWS de AWS Secrets Manager. |
`PIX_VENDOR_SUBJECTS` lista las identidades de JD que pueden llamar a `pix-ingress`. El Courier rechaza a todos los otros llamadores, incluidos los motores.
El Courier lee el client ID y el secret de cada motor desde AWS Secrets Manager, en `AWS_REGION`. Guárdalos allí antes de registrar el motor. Sin acceso a AWS Secrets Manager, el Courier mantiene los mensajes Pix del motor y no los entrega.
Guarda el secret de cada motor en `tenants/{ENVIRONMENT_NAME}/{tenantId}/jd-courier/external/pix-engine-{engineId}/credentials/versions/{versionId}`. `pixDelivery.credentialRef` debe apuntar a ese secret. El Courier no entrega al motor cuando la referencia apunta a cualquier otra ruta. El secret es un objeto JSON con los campos `clientId` y `clientSecret`. `{versionId}` es un UUID en minúsculas. En modo single-tenant, `{tenantId}` es el ID del tenant del canal Pix activo del Courier.
### Licencia
| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `LICENSE_KEY` | 🔒 **Obligatorio** | Tu clave de licencia de Lerian. |
| `ORGANIZATION_IDS` | — | El ID de tu organización. |
| `APPLICATION_NAME` | `jd-courier` | El nombre de la aplicación que usa la verificación de la licencia. |
## Comportamiento de la licencia
***
El Courier verifica la licencia en el arranque. No reinicies un pod mientras la licencia no sea válida: el pod no arranca hasta que corrijas la licencia.
Mientras el proceso se ejecuta, el Courier verifica la licencia de nuevo cada 6 horas. Cuando la licencia queda revocada, el proceso sigue activo:
* La API del operador y la API de los motores responden `503 JDC-0902`.
* La dirección Pix y la interfaz SOAP responden `503`.
* El rol `spb-consumer` deja de leer de JD.
La sonda `/readyz` informa el estado de la licencia. Mientras la licencia está revocada, el Courier la verifica de nuevo después de 1 minuto, y el intervalo se duplica hasta 15 minutos. Con la primera respuesta válida, el Courier vuelve a servir sin reinicio.
Modo multi-tenant
***
El modo multi-tenant permite que un despliegue del Courier atienda a más de un cliente. Lerian Cloud ejecuta el Courier en este modo, y Lerian opera el despliegue. Las otras secciones de esta página describen un despliegue single-tenant.
`MULTI_TENANT_ENABLED=true` activa el modo. Para las otras variables `MULTI_TENANT_*`, consulta [Aspectos esenciales de la configuración de BYOC](/es/reference/byoc-configuration) y [Multi-tenancy](/es/platform/multi-tenancy).
En [modo multi-tenant](/es/platform/multi-tenancy), la API del operador, la API de los motores y el Pix ingress toman el tenant del token verificado de quien llama. La dirección SOAP toma el tenant de la credencial de canal.
### Qué cambia respecto de single-tenant
* El rol `spb-consumer` sigue ejecutándose como exactamente una réplica. Lee de JD para cada tenant que tiene un canal SPB activo.
* El rol `spb-consumer` lee la lista de tenants de nuevo cada 30 segundos (`SPB_TENANT_REFRESH_SEC`). Cuando la base de datos de un tenant no responde, el rol omite ese tenant en esa pasada. Los otros tenants continúan.
* La conciliación ejecuta un ciclo para cada tenant y riel.
* El rol `pix-ingress` requiere `SYSTEMPLANE_ENABLED=true`. Sin ella, el proceso no arranca.
* El chart no ejecuta el job de migraciones. Define `migrations.enabled=false`: el chart se niega a renderizar el job en este modo. Aplica las migraciones de cada tenant a través de Tenant Manager.
En modo multi-tenant, el Courier ignora `JD_BASE_URL`, `JD_SOAP_PATH`, `JD_LEGACY_CODE`, `JD_USER_CODE` y `JD_PASSWORD`. Lee la dirección JD y la credencial JD de cada tenant desde AWS Secrets Manager.
En modo multi-tenant, el Courier ignora `PIX_VENDOR_SUBJECTS`. La clave de configuración en tiempo de ejecución `jd-courier.pix/vendor_subjects` lista las identidades de JD de cada tenant. El Courier responde 503 a todas las llamadas Pix de JD para un tenant sin entrada.
En modo multi-tenant, el Courier no arranca con `PLUGIN_AUTH_ENABLED=false`. Pon `MULTI_TENANT_SERVICE_API_KEY` y `MULTI_TENANT_REDIS_PASSWORD` en el Secret de Kubernetes.
### Quién configura qué en Lerian Cloud
* **Lerian** configura el despliegue: las variables de entorno, la configuración en tiempo de ejecución y las migraciones de cada tenant.
* **Tu operador** usa la API del operador como en un despliegue single-tenant: los motores, el mapa de titularidad, los modos de entrega, el bypass, los mensajes retenidos y la conciliación.
* **Tus motores** usan la API de los motores, la interfaz SOAP y la dirección Pix como en un despliegue single-tenant.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.