Deployment and configuration

Run JD Courier in your infrastructure: the four roles, the two ports, the environment variables, and the license behavior.

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.
• The address of your Access Manager.
• Your Lerian license key and organization ID.
• The SPB channel settings 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.

Role	Replicas	Service port	What it serves
spb-consumer	Exactly 1	None	Reads the SPB messages from JD and routes them.
spb-sender	2	8081	The SOAP interface for the engines.
pix-ingress	2	8080	The address where JD sends the Pix calls.
admin	1	8080	The operator API, the engine API, and reconciliation.

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

---

Port	Variable	Default	Serves
HTTP	SERVER_ADDRESS	:8080	The probes, the operator API, the engine API, and the Pix address.
SOAP	SOAP_SERVER_ADDRESS	:8081	The SOAP interface, on the spb-sender role only.

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, DATABASE_URL and JD_PASSWORD in your secret vault.

The Courier does not apply database migrations at boot. Apply them before each install and upgrade.

Environment variables

---

This section lists the variables of the Courier. For the datastore, telemetry, and authentication variables that every Lerian service shares, see BYOC configuration essentials.

In the tables below, the Default / Required column shows the default value. Required marks the variables that you must set. — means no default. 🔒 marks a secret.

Service

Variable	Default / Required	Description
COURIER_ROLES	Required	The roles of the process, separated by commas: spb-consumer, spb-sender, pix-ingress, admin.
ENVIRONMENT_NAME	development	The environment. Set production in production: the Courier then applies its production checks at boot.
DEPLOYMENT_MODE	local	byoc, saas, or local. Another value stops the boot.
HTTP_BODY_LIMIT_BYTES	1048576	The largest request body on the HTTP port.
POSTGRES_SSLMODE	disable	With disable, the Courier does not start unless ALLOW_INSECURE_TLS=true. Use verify-full in production.

JD SPB channel

The two SPB roles read these variables.

Variable	Default / Required	Description
JD_BASE_URL	Required in production	The address of the JD SPB service.
JD_SOAP_PATH	/soap	The path of the JD SOAP service.
JD_LEGACY_CODE	Required in production	See the note below.
JD_USER_CODE	Required in production	See the note below.
JD_PASSWORD	🔒 Required in production	See the note below.
SPB_VENDOR_TIMEOUT	7s	How long the Courier waits for JD. It must be more than zero and less than 8s.

JD_LEGACY_CODE, JD_USER_CODE and JD_PASSWORD are the JD credentials you already hold (up to 10, 10 and 20 characters). In production, use https for JD_BASE_URL.

SOAP interface

The spb-sender role reads these variables.

Variable	Default / Required	Description
SOAP_MAX_BODY_BYTES	10485760	The largest SOAP request body.
SPB_CHANNEL_CREDENTIAL_ROTATION_OVERLAP	24h	See the note below.
SOAP_TLS_CERT_FILE	—	See the note below.
SOAP_TLS_KEY_FILE	—	See the note below.
SOAP_TLS_TERMINATED_UPSTREAM	false	See the note below.

In production, give spb-sender a TLS certificate and key (SOAP_TLS_CERT_FILE, SOAP_TLS_KEY_FILE), or set SOAP_TLS_TERMINATED_UPSTREAM when TLS ends before the Courier. The minimum TLS version is 1.2.

Pix

Variable	Default / Required	Description
PIX_VENDOR_SUBJECTS	Required for pix-ingress	See the note below.
AWS_REGION	us-east-1	The AWS region of AWS Secrets Manager.

PIX_VENDOR_SUBJECTS lists the JD identities that can call pix-ingress. The Courier refuses every other caller, engines included.

The Courier reads each engine’s client ID and secret from AWS Secrets Manager, in AWS_REGION. Store them there before you register the engine. Without access to AWS Secrets Manager, the Courier keeps the engine’s Pix messages and does not deliver them.

Store each engine’s secret under tenants/{ENVIRONMENT_NAME}/{tenantId}/jd-courier/external/pix-engine-{engineId}/credentials/versions/{versionId}. pixDelivery.credentialRef must point to that secret. 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 the Pix rail.

License

Variable	Default / Required	Description
LICENSE_KEY	🔒 Required	Your Lerian license key.
ORGANIZATION_IDS	—	Your organization ID.
APPLICATION_NAME	jd-courier	The application name that the license check uses.

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 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 Pix secret path uses. 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 any of the variables on this page.

• Lerian configures and runs the deployment.
• Your operator uses the operator API: the engines, the ownership map, the delivery modes, bypass, the retained messages, and reconciliation.
• Your engines use the engine API, the SOAP interface, and the Pix address.