Container Build Strategy for API, Worker, and Side Services
Overview
This section documents how Dwilar/lita-api turns the monorepo API and worker into production container images, and how the standalone side services are packaged beside them. The main API image is built from the workspace root with pnpm, shared packages, and a TypeScript build step; the worker uses the same workspace build pattern but runs as a background poller instead of an HTTP server.
The deployment split is visible directly in the Dockerfiles: apps/api and apps/worker are monorepo-aware Node 20 images, while services/consent-service and services/scoring-orchestrator are self-contained Node 18 images, and services/token-service plus services/us-data-gateway are multi-stage Go binaries. docker-compose.api.yml is the composition layer that assembles these images into a single runtime stack.
Architecture Overview
flowchart TB
subgraph WorkspaceBuild [Monorepo Workspace Build]
RootManifests[Root package json pnpm workspace yaml turbo json tsconfig base json]
SharedPackages[packages directory]
ApiDockerfile[apps api Dockerfile]
WorkerDockerfile[apps worker Dockerfile]
ApiBuild[apps api build]
WorkerBuild[apps worker build]
ApiRuntime[apps api runtime image]
WorkerRuntime[apps worker runtime image]
RootManifests --> ApiDockerfile
RootManifests --> WorkerDockerfile
SharedPackages --> ApiDockerfile
SharedPackages --> WorkerDockerfile
ApiDockerfile --> ApiBuild
WorkerDockerfile --> WorkerBuild
ApiBuild --> ApiRuntime
WorkerBuild --> WorkerRuntime
end
subgraph StandaloneServices [Standalone Side Services]
ConsentDockerfile[services consent service Dockerfile]
ScoreDockerfile[services scoring orchestrator Dockerfile]
TokenDockerfile[services token service Dockerfile]
GatewayDockerfile[services us data gateway Dockerfile]
ConsentRuntime[consent service image]
ScoreRuntime[scoring orchestrator image]
TokenRuntime[token service image]
GatewayRuntime[us data gateway image]
ConsentDockerfile --> ConsentRuntime
ScoreDockerfile --> ScoreRuntime
TokenDockerfile --> TokenRuntime
GatewayDockerfile --> GatewayRuntime
end
ComposeFile[docker compose api yml]
ComposeFile --> ApiRuntime
ComposeFile --> WorkerRuntime
ComposeFile --> ConsentRuntime
ComposeFile --> ScoreRuntime
ComposeFile --> TokenRuntime
ComposeFile --> GatewayRuntime
Container Image Matrix
| Image | Build family | Base image | Build tool | Runtime artifact | Port |
|---|---|---|---|---|---|
apps/api |
Monorepo Node | node:20-alpine |
pnpm + tsc |
dist/index.js |
3000 |
apps/worker |
Monorepo Node | node:20-alpine |
pnpm + tsc |
dist/index.js |
none |
services/consent-service |
Standalone Node | node:18-alpine |
npm ci |
src/index.js |
8081 |
services/scoring-orchestrator |
Standalone Node | node:18-alpine |
npm ci |
src/index.js |
8082 |
services/token-service |
Standalone Go | golang:1.20-alpine then alpine:3.19 |
go build |
/bin/token-service |
8083 |
services/us-data-gateway |
Standalone Go | golang:1.20-alpine then alpine:3.19 |
go build |
/bin/us-data-gateway |
8084 |
Workspace-Built Node Images
API Image Build
apps/api/Dockerfile, apps/api/package.json, apps/api/tsconfig.json, apps/api/src/index.ts, apps/api/src/server.ts
The API image is built as a two-stage image. The build stage copies the workspace manifests, the app manifest, the app TypeScript config, and the shared packages tree before running pnpm install --frozen-lockfile; this is what makes the image workspace-aware instead of app-only. After the source tree is copied in, pnpm -C apps/api build compiles the server into dist.
The runtime stage copies only dist and package.json, sets NODE_ENV=production, exposes 3000, and starts node dist/index.js.
Build inputs
| File | Role in the image |
|---|---|
package.json |
Root workspace manifest copied before dependency install |
pnpm-workspace.yaml |
Defines the workspace layout for pnpm install |
turbo.json |
Workspace build configuration copied into the build context |
tsconfig.base.json |
Shared TypeScript base config copied into the build context |
apps/api/package.json |
Declares @lita/api, its build script, and runtime dependencies |
apps/api/tsconfig.json |
Compiles src into dist |
packages/ |
Shared workspace packages used by the API build |
Runtime contract
| Setting | Value |
|---|---|
| Runtime base | node:20-alpine |
| Output copied into image | /app/apps/api/dist |
| Runtime entrypoint | node dist/index.js |
| Container port | 3000 |
| Runtime mode | NODE_ENV=production |
API bootstrap flow
apps/api/src/index.ts starts the compiled server by calling buildServer(), resolving PORT from the environment with a default of 3000, fixing the host to 0.0.0.0, and then calling server.listen({ port, host }). The process logs the chosen port after the listener is up.
apps/api/src/server.ts builds the Fastify instance, initializes OpenTelemetry with initOtel(), installs the logger from buildLogger(), and then wires cors, helmet, rateLimit, authPlugin, tenantPlugin, idempotencyPlugin, and auditPlugin before registering the versioned routes.
| Function | Responsibility |
|---|---|
buildServer |
Creates the Fastify app, initializes telemetry, registers plugins, and mounts routes and probes |
server.listen |
Binds the API container to the configured host and port |
Worker Image Build
apps/worker/Dockerfile, apps/worker/package.json, apps/worker/tsconfig.json, apps/worker/src/index.ts
The worker uses the same workspace build pattern as the API. The build stage copies the root workspace manifests, the worker package manifest, the worker TypeScript config, and the shared packages tree, then runs pnpm install --frozen-lockfile. After the worker source is copied in, pnpm -C apps/worker build emits dist.
The runtime image again copies only dist and package.json, sets NODE_ENV=production, and runs node dist/index.js. Unlike the API, the worker exposes no port because it is a background process.
Build inputs
| File | Role in the image |
|---|---|
package.json |
Root workspace manifest copied before dependency install |
pnpm-workspace.yaml |
Defines the workspace layout for pnpm install |
turbo.json |
Workspace build configuration copied into the build context |
tsconfig.base.json |
Shared TypeScript base config copied into the build context |
apps/worker/package.json |
Declares @lita/worker, its build script, and runtime dependencies |
apps/worker/tsconfig.json |
Compiles src into dist |
packages/ |
Shared workspace packages used by the worker build |
Runtime contract
| Setting | Value |
|---|---|
| Runtime base | node:20-alpine |
| Output copied into image | /app/apps/worker/dist |
| Runtime entrypoint | node dist/index.js |
| Container port | none |
| Runtime mode | NODE_ENV=production |
Worker execution flow
apps/worker/src/index.ts runs a perpetual polling loop. pollDeliveries() queries prisma.webhookDelivery.findMany() for deliveries whose status is pending or retrying and whose nextRetryAt is null or due, then processes up to 10 records at a time. processDelivery() loads the delivery and its endpoint, signs the payload with signWebhook(), POSTs the payload to the endpoint, and updates delivery state in Prisma based on success or failure.
| Function | Responsibility |
|---|---|
processDelivery |
Signs and sends a webhook delivery, then updates delivery state and audit trail |
pollDeliveries |
Fetches due deliveries from Prisma and dispatches them one by one |
run |
Repeats polling every 5000 ms and logs poll failures |
sequenceDiagram
participant Worker as run
participant Poll as pollDeliveries
participant DB as prisma
participant Process as processDelivery
participant Sign as signWebhook
participant Endpoint as Delivery endpoint
participant Audit as recordAuditEvent
Worker->>Poll: poll every 5000 ms
Poll->>DB: findMany due deliveries
DB-->>Poll: delivery list
loop each delivery
Poll->>Process: deliveryId
Process->>DB: findUnique delivery with endpoint
Process->>Sign: sign payload
Process->>Endpoint: POST payload with headers
alt success
Process->>DB: update delivered
else failure
Process->>DB: update retrying or failed
Process->>Audit: webhook.delivery.failed
end
end
Standalone Side Service Images
Consent Service Image Build
services/consent-service/Dockerfile
services/consent-service/Dockerfile is a single-stage Node image. It installs dependencies with npm ci --omit=dev, copies src, sets NODE_ENV=production, exposes 8081, and starts node src/index.js.
| Setting | Value |
|---|---|
| Runtime base | node:18-alpine |
| Dependency install | npm ci --omit=dev |
| Runtime entrypoint | node src/index.js |
| Container port | 8081 |
| Build style | Single-stage runtime image |
Scoring Orchestrator Image Build
services/scoring-orchestrator/Dockerfile
services/scoring-orchestrator/Dockerfile uses the same single-stage Node pattern as the consent service. It installs production dependencies with npm ci --omit=dev, copies src, exposes 8082, and launches node src/index.js.
| Setting | Value |
|---|---|
| Runtime base | node:18-alpine |
| Dependency install | npm ci --omit=dev |
| Runtime entrypoint | node src/index.js |
| Container port | 8082 |
| Build style | Single-stage runtime image |
Token Service Image Build
services/token-service/Dockerfile
services/token-service/Dockerfile is a multi-stage Go build. The build stage downloads modules after setting GOPROXY=direct, copies the full source tree, and builds /bin/token-service from ./cmd/token-service. The runtime stage is a slim alpine:3.19 image that creates a non-root app user, sets PORT=8083, exposes 8083, copies in the binary, and uses it as the entrypoint.
| Setting | Value |
|---|---|
| Build base | golang:1.20-alpine |
| Runtime base | alpine:3.19 |
| Runtime user | app |
| Runtime entrypoint | /bin/token-service |
| Container port | 8083 |
| Build style | Multi-stage binary image |
US Data Gateway Image Build
services/us-data-gateway/Dockerfile
services/us-data-gateway/Dockerfile follows the same Go packaging model as the token service. It builds /bin/us-data-gateway from ./cmd/us-data-gateway, runs it inside alpine:3.19, creates the non-root app user, sets PORT=8084, exposes 8084, and uses the binary as the entrypoint.
| Setting | Value |
|---|---|
| Build base | golang:1.20-alpine |
| Runtime base | alpine:3.19 |
| Runtime user | app |
| Runtime entrypoint | /bin/us-data-gateway |
| Container port | 8084 |
| Build style | Multi-stage binary image |
Runtime Coupling and Operational Movement
| Operational set | Containers | Why they are coupled |
|---|---|---|
| Core monorepo pair | apps/api, apps/worker |
Shared workspace build, shared packages, shared database-backed delivery flow |
| Node side services | services/consent-service, services/scoring-orchestrator |
Separate Node images with their own package-lock and src/index.js entrypoints |
| Go side services | services/token-service, services/us-data-gateway |
Separate binary images with fixed ports and non-root runtime users |
Observability, Audit, and Delivery Infrastructure
Observability Bootstrap
[!IMPORTANT]
apps/apiandapps/workerare the only images that are built from the same workspace root and share the same monorepo package set. They form the release pair in this repository because the worker consumes the webhook delivery records that the API side creates and because both images depend on the same shared workspace packages.
apps/api/src/server.ts
The API container initializes telemetry before any Fastify registration happens. buildServer() calls initOtel() first, then creates Fastify with the logger returned by buildLogger(). That means telemetry and logging are part of the server bootstrap path, not a later plugin.
| Function | Responsibility |
|---|---|
initOtel |
Initializes OpenTelemetry before the HTTP server is constructed |
buildLogger |
Supplies the logger instance used by Fastify |
buildServer |
Connects telemetry, logging, plugins, and routes in one startup path |
Webhook Delivery Worker
apps/worker/src/index.ts, apps/api/src/routes/v1/webhooks.ts
The worker is the delivery engine for webhook records. The API side creates and queues webhook deliveries through @lita/webhooks, while the worker reads due rows from prisma.webhookDelivery, signs the body with signWebhook(), and sends the delivery to the endpoint URL. On failure it increments the attempt counter, schedules a retry, and writes an audit event through recordAuditEvent().
| Component | Responsibility |
|---|---|
enqueueWebhookDelivery |
API-side queueing of webhook deliveries |
processDelivery |
Worker-side transport and state transitions |
signWebhook |
Produces the X-Lita-Signature value used for delivery verification |
recordAuditEvent |
Records delivery failure events in the audit trail |
sequenceDiagram
participant API as API side
participant Queue as enqueueWebhookDelivery
participant DB as prisma
participant Worker as pollDeliveries
participant Process as processDelivery
participant Endpoint as Delivery endpoint
participant Audit as recordAuditEvent
API->>Queue: create webhook delivery
Queue->>DB: persist delivery row
Worker->>DB: findMany due deliveries
DB-->>Worker: delivery rows
Worker->>Process: deliveryId
Process->>DB: load delivery and endpoint
Process->>Endpoint: POST signed payload
alt delivery accepted
Process->>DB: mark delivered
else delivery rejected
Process->>DB: mark retrying or failed
Process->>Audit: webhook.delivery.failed
end
Runtime Probe Endpoints
apps/api/src/server.ts registers three public probe/documentation endpoints after the plugin stack is installed. The auth plugin treats /healthz, /readyz, and /openapi.json as public paths, so they bypass auth while still flowing through the global Fastify stack.
Health Check
apps/api/src/server.ts
Health Check
{
"title": "Health Check",
"description": "Returns the public liveness probe response. The route is exempt from auth through the auth plugin publicPaths set.",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/healthz",
"headers": [],
"queryParams": [],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"status\": \"ok\"\n}"
}
}
}
Readiness Check
apps/api/src/server.ts
Readiness Check
{
"title": "Readiness Check",
"description": "Returns the public readiness probe response. The route is exempt from auth through the auth plugin publicPaths set.",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/readyz",
"headers": [],
"queryParams": [],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"status\": \"ready\"\n}"
}
}
}
OpenAPI Document
apps/api/src/server.ts
OpenAPI Document
{
"title": "OpenAPI Document",
"description": "Returns the OpenAPI document payload emitted by the API process. The route is exempt from auth through the auth plugin publicPaths set.",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/openapi.json",
"headers": [],
"queryParams": [],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"openapi\": \"3.0.3\",\n \"info\": {\n \"title\": \"Lita Platform API\",\n \"version\": \"1.2.0\"\n },\n \"paths\": []\n}"
}
}
}
Compose Assembly
[!NOTE]
GET /openapi.jsonreturns a static object withpaths: {}even thoughbuildServer()registers route plugins and probe endpoints. The emitted document does not enumerate the live HTTP surface.
docker-compose.api.yml
docker-compose.api.yml is the orchestration layer for the image set documented here. It is the file that brings the workspace-built API and worker together with the standalone consent, scoring, token, and US gateway services.
Key Classes Reference
| Class | Responsibility |
|---|---|
apps/api/Dockerfile |
Builds the monorepo API image from the workspace and emits the production runtime container |
apps/worker/Dockerfile |
Builds the monorepo worker image and packages the webhook delivery loop |
services/consent-service/Dockerfile |
Packages the standalone consent service as a production Node container |
services/scoring-orchestrator/Dockerfile |
Packages the standalone scoring orchestrator as a production Node container |
services/token-service/Dockerfile |
Builds the token service into a non-root Go binary image |
services/us-data-gateway/Dockerfile |
Builds the US data gateway into a non-root Go binary image |
apps/api/src/server.ts |
Creates the Fastify server, telemetry, plugins, routes, and public probe endpoints |
apps/api/src/index.ts |
Resolves the runtime port and starts the API listener |
apps/worker/src/index.ts |
Runs the webhook delivery polling loop and delivery processor |
docker-compose.api.yml |
Composes the service images into a single deployment stack |