Skip to main content
In BYOC, you run the Courier in your own environment. One image runs in four roles. On Lerian Cloud, Lerian operates the Courier: see On Lerian Cloud.

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.
  1. Create a partner for JD in your Access Manager.
  2. Give the partner the JD Courier permission pix-ingress with the action post.
  3. Create the partner’s application, and give its client ID and secret to JD.
The Courier refuses with 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 503 with X-Send-Outcome: not-sent.
  • The spb-consumer role stops reading from JD.
The /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.
The answer gives the identifier that the secret paths of the engine credentials use. The activation history lists each activation and suspension of a rail, with its operator. One installation holds each rail. When the rail is already active for another holder, the activation answers 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.