Before you start
Make sure that you have these items:
- A PostgreSQL database for the Courier.
- Access Manager v3.12.0 or later, and its address.
- Your Lerian license key.
- The SPB channel settings that JD gave your institution.
- For the Pix transit, the SPI cabin credential that JD gave your institution.
The four roles
One binary carries the four roles. The variable
COURIER_ROLES selects the roles of a process. It has no default: a process without it does not start.
Run
spb-consumer as exactly one replica. A read from the JD queue removes the message, so the consumer is a single writer. A process that combines spb-consumer with another role stops at boot with the code JDC-0314.
Ports
Every role answers the probes on the HTTP port:
/health for liveness, /readyz for readiness, and /version for the build.
Install
To install or upgrade the Courier, see the JD Courier chart README. Keep
LICENSE_KEY, POSTGRES_PASSWORD, JD_PASSWORD, JD_SPI_CLIENT_SECRET and IDP_M2M_CLIENT_SECRET in your secret vault.
The Courier does not apply database migrations at boot. Apply them before each install and upgrade.
Environment variables
The variables of the Courier, with their defaults and their effects, are in JD Courier environment variables.
Access Manager
In single-tenant mode, the Courier publishes its partner opt-in to your Access Manager. With
IDP_DECLARATION_ENABLED=true, it also publishes its permissions. Both need IDP_HOST, IDP_M2M_CLIENT_ID and IDP_M2M_CLIENT_SECRET. Until your Access Manager accepts the publication, /readyz reports permission_declaration as degraded, with the reason.
JD as a partner
JD calls your Pix address as an Access Manager partner of your installation.- Create a partner for JD in your Access Manager.
- Give the partner the JD Courier permission
pix-ingresswith the actionpost. - Create the partner’s application, and give its client ID and secret to JD.
401 every caller of the Pix address that is not an Access Manager partner, engines included.
Engine credentials
The Courier reads the credential that it uses at each engine from AWS Secrets Manager, in
AWS_REGION. Store it there before you register the address of the engine.
The reference must point to the secret of that engine. The Courier does not deliver to the engine when the reference points to any other path. The secret is a JSON object with the fields
clientId and clientSecret. {versionId} is a lowercase UUID. {tenantId} is the identifier in the answer to the activation of a rail. In single-tenant mode, it is local. In multi-tenant mode, it is the tenant of the validated token.
Pix transit
The Pix transit lets the engines send their own Pix calls to JD through the Courier. To turn it on, set
PIX_TRANSIT_SERVER_ADDRESS on the admin role. The transit listens on that address, with its own TLS settings. The Courier calls JD with the SPI cabin credential of your institution: JD_SPI_BASE_URL, JD_SPI_CLIENT_ID and JD_SPI_CLIENT_SECRET.
When JD sends asynchronous account validations to your institution, set both the Pix transit and the SPI cabin credential. The engines send their validation results through the transit. The Courier sends its own refusals with the SPI cabin credential.
Do not put a proxy that retries a 503 between the engines and the transit. For the answers of the transit, see Connecting an engine.
License behavior
The Courier checks the license at boot. Do not restart a pod while the license is not valid: the pod does not start until you fix the license. While the process runs, the Courier checks the license again every 6 hours. When the license becomes revoked, the process stays up:
- The operator API and the engine API answer
503 JDC-0902. - The Pix address and the SOAP interface answer
503. - The Pix transit answers
503withX-Send-Outcome: not-sent. - The
spb-consumerrole stops reading from JD.
/readyz probe reports the license state. While the license is revoked, the Courier checks it again after 1 minute, and the interval doubles up to 15 minutes. At the first valid answer, the Courier serves again with no restart.
Activate the rails
The Courier delivers no message of a rail to the engines until an operator activates the rail. To activate a rail, use the operation Activate a rail of the operator API. It requires the
activation:write permission on the channels resource.
- SPB. Activate SPB at cutover, when no engine reads from JD directly. After the activation, the Courier reads the messages from the JD queue, and a read removes the message from JD.
- Pix. Activate Pix before you ask JD to send the Pix calls to the Courier.
409 JDC-0117.
On Lerian Cloud
On Lerian Cloud, Lerian operates the Courier. You do not set its environment variables.
- Lerian configures and runs the deployment.
- Your operator uses the operator API: the engines, the ownership map, the delivery modes, the retained messages, and reconciliation.
- Your engines use the engine API, the SOAP interface, and the Pix address.

