Deployment and configuration

In BYOC, you deploy the Courier in your own Kubernetes cluster with its Helm chart. The chart runs one image in four roles, one deployment for each role. On Lerian Cloud, Lerian operates the Courier in multi-tenant mode.

Before you start

Make sure that you have these items:

A Kubernetes cluster and Helm.
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. The chart sets it for each deployment, and it refuses a value in config.

Role	Replicas in the chart	Service port	What it serves
`spb-consumer`	Exactly `1`, with the `Recreate` strategy	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. The chart refuses to render more than one replica. 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.

The chart derives both variables from ports.http and ports.soap. Every role answers the probes on the HTTP port: /health for liveness, /readyz for readiness, and /version for the build.

Install with Helm

The chart is oci://ghcr.io/lerianstudio/br-jd-courier-helm. Read its versions before you pin one:

helm show chart oci://ghcr.io/lerianstudio/br-jd-courier-helm

Create the Secret that every role reads. The chart does not create it. Put LICENSE_KEY, POSTGRES_PASSWORD, DATABASE_URL and, in single-tenant mode, JD_PASSWORD in a Kubernetes Secret that you create. The chart refuses these keys in its config values.
Write your values file. Put the non-secret variables under config. The chart puts them in one ConfigMap that every role reads.

Install the chart:

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

Before each install and upgrade, the chart runs a job that applies the database migrations. The Courier does not apply migrations at boot.

Environment variables

This section lists the variables of the Courier. For the datastore, multi-tenancy, 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`. The chart sets it.
`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. In single-tenant mode, {tenantId} is the tenant ID of the Courier’s active Pix channel.

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.

Multi-tenant mode

Multi-tenant mode lets one deployment of the Courier serve more than one client. Lerian Cloud runs the Courier in this mode, and Lerian operates the deployment. The other sections of this page describe a single-tenant deployment. MULTI_TENANT_ENABLED=true turns the mode on. For the other MULTI_TENANT_* variables, see BYOC configuration essentials and Multi-tenancy. In multi-tenant mode, the operator API, the engine API and the Pix ingress take the tenant from the caller’s verified token. The SOAP address takes the tenant from the channel credential.

What changes from single-tenant

The spb-consumer role still runs as exactly one replica. It reads from JD for each tenant that has an active SPB channel.
The spb-consumer role reads the tenant list again every 30 seconds (SPB_TENANT_REFRESH_SEC). When the database of a tenant does not answer, the role skips that tenant for that pass. The other tenants continue.
Reconciliation runs one cycle for each tenant and rail.
The pix-ingress role requires SYSTEMPLANE_ENABLED=true. Without it, the process does not start.
The chart does not run the migrations job. Set migrations.enabled=false: the chart refuses to render the job in this mode. Apply the migrations of each tenant through Tenant Manager.

In multi-tenant mode, the Courier ignores JD_BASE_URL, JD_SOAP_PATH, JD_LEGACY_CODE, JD_USER_CODE and JD_PASSWORD. It reads each tenant’s JD address and JD credential from AWS Secrets Manager. In multi-tenant mode, the Courier ignores PIX_VENDOR_SUBJECTS. The runtime configuration key jd-courier.pix/vendor_subjects lists the JD identities for each tenant. The Courier answers 503 to every JD Pix call for a tenant with no entry. In multi-tenant mode, the Courier does not start with PLUGIN_AUTH_ENABLED=false. Put MULTI_TENANT_SERVICE_API_KEY and MULTI_TENANT_REDIS_PASSWORD in the Kubernetes Secret.

Who configures what on Lerian Cloud

Lerian configures the deployment: the environment variables, the runtime configuration, and the migrations of each tenant.
Your operator uses the operator API as in a single-tenant deployment: 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 as in a single-tenant deployment.

Overview

Setup

Operations

Deployment and configuration

Before you start

The four roles

Ports

Install with Helm

Environment variables

Service

JD SPB channel

SOAP interface

Pix

License

License behavior

Multi-tenant mode

What changes from single-tenant

Who configures what on Lerian Cloud

​Before you start

​The four roles

​Ports

​Install with Helm

​Environment variables

​Service

​JD SPB channel

​SOAP interface

​Pix

​License

​License behavior

​Multi-tenant mode

​What changes from single-tenant

​Who configures what on Lerian Cloud

Before you start

The four roles

Ports

Install with Helm

Environment variables

Service

JD SPB channel

SOAP interface

Pix

License

License behavior

Multi-tenant mode

What changes from single-tenant

Who configures what on Lerian Cloud