Deployment, Gateway, and Infrastructure

Overview

This section covers how the US and JP API surfaces are moved onto a new VM, how the public gateway is expected to sit in front of the services, and which runtime inputs the deployment expects before cutover. The migration guide is operational rather than application-level: it focuses on provisioning, wiring shared dependencies, validating service reachability, and switching api.joinlita.com to the new host.

The repository also exposes the current infrastructure state clearly: the Terraform area is a skeleton, not a complete production IaC implementation. The only documented production inputs are the runtime variables in services/us-api/.env.example and the prerequisite secrets and endpoints listed in documents/us-jp-api-vm-migration.md.

Architecture Overview

Files: documents/us-jp-api-vm-migration.md, services/us-api/.env.example, services/consent-service/Dockerfile, services/scoring-orchestrator/Dockerfile, services/token-service/Dockerfile, services/us-data-gateway/Dockerfile

flowchart TD
    Client[Partner Client] --> DNS[api.joinlita.com DNS]

    subgraph PublicEdge[Public Edge]
        DNS --> Kong[Kong proxy]
    end

    subgraph ApplicationVM[New VM]
        USAPI[US API service port 8080]
        ConsentService[consent-service port 8081]
        ScoringOrchestrator[scoring-orchestrator port 8082]
        TokenService[token-service port 8083]
        USDatGateway[us-data-gateway port 8084]
    end

    subgraph SharedDependencies[Shared Dependencies]
        Postgres[Postgres]
        Redis[Redis]
    end

    Kong --> USAPI
    Kong --> ConsentService
    Kong --> ScoringOrchestrator
    Kong --> TokenService
    Kong --> USDatGateway

    USAPI --> Postgres
    USAPI --> Redis
    ConsentService --> Postgres
    ConsentService --> Redis
    ScoringOrchestrator --> Postgres
    ScoringOrchestrator --> Redis
    TokenService --> Postgres
    TokenService --> Redis
    USDatGateway --> Postgres
    USDatGateway --> Redis

Runtime Surfaces and Ports

Files: services/us-api/.env.example, services/consent-service/Dockerfile, services/scoring-orchestrator/Dockerfile, services/token-service/Dockerfile, services/us-data-gateway/Dockerfile, documents/us-jp-api-vm-migration.md

Service Runtime shape Port Deployment evidence
us-api Node/TypeScript container 8080 PORT=8080 in .env.example; docker run -p 8080:8080 in the migration guide
consent-service node:18-alpine runtime 8081 EXPOSE 8081
scoring-orchestrator node:18-alpine runtime 8082 EXPOSE 8082
token-service Go binary in alpine:3.19 runtime 8083 ENV PORT=8083, EXPOSE 8083
us-data-gateway Go binary in alpine:3.19 runtime 8084 ENV PORT=8084, EXPOSE 8084

VM Migration Runbook

[!IMPORTANT] The migration guide treats the US API plus consent-service, token-service, us-data-gateway, and scoring-orchestrator as a shared cutover set. They are expected to move together or remain reachable from the new VM.

File: documents/us-jp-api-vm-migration.md

1) Provision the new VM

Install Docker and the system packages needed by the Node and Go services. Configure firewall rules and security groups before exposing any traffic.

2) Collect deployment inputs

The migration guide requires these runtime and infrastructure values before cutover:

  • Postgres connection string for production
  • Redis host and port
  • DATABASE_URL
  • REDIS_URL
  • JWT_PRIVATE_KEY
  • JWT_PUBLIC_KEY
  • PARTNER_API_KEYS
  • PROVIDER
  • SCORING_CALLBACK_URL
  • new VM IP address
  • DNS or load balancer target for api.joinlita.com
  • inbound firewall plan
  • allowlist, security group, or VPC peering rules for client systems that must reach the API

3) Build the US API image

cd services/us-api
docker build -t us-api:latest .

4) Start the US API container

docker run -d --name us-api \
  -p 8080:8080 \
  -e DATABASE_URL=... \
  -e REDIS_URL=... \
  -e JWT_PRIVATE_KEY="..." \
  -e JWT_PUBLIC_KEY="..." \
  -e PARTNER_API_KEYS="..." \
  -e PROVIDER=... \
  -e SCORING_CALLBACK_URL="..." \
  us-api:latest

5) Start the supporting services

[!IMPORTANT] The guide explicitly states that the repository does not include a production deployment config. The docker run example is only an illustration, and production should use a dedicated deployment manifest or compose definition.

Bring up the remaining services alongside the US API service:

  • consent-service
  • token-service
  • us-data-gateway
  • scoring-orchestrator

Use the service-specific runtime or build instructions for each one, and keep the ports aligned with the published container defaults.

6) Verify dependency connectivity

Check that the new VM can reach:

  • Postgres
  • Redis
  • the internal services that the US API depends on

The migration guide treats this as a hard prerequisite before traffic moves.

7) Validate with smoke tests

Run the repository’s Postman/Newman collection against the new VM:

newman run services/us-api/postman/us-api.postman_collection.json \
  -e services/us-api/postman/us-api.postman_environment.json \
  --env-var baseUrl=http://<NEW_VM_IP>:8080 \
  --env-var partnerToken=<PARTNER_API_KEY>

The guide also instructs you to confirm the service health endpoint during validation.

8) Cut over traffic

Update DNS or load balancer targets so api.joinlita.com resolves to the new VM. The guide treats Kong as the public entrypoint, so the public target should point at the Kong proxy port on the new host.

9) Monitor and decommission

After traffic has stabilized:

  • monitor logs and health checks
  • confirm there are no elevated errors
  • shut down the old VM

Migration sequence

sequenceDiagram
    participant Ops as Operator
    participant VM as New VM
    participant Kong as Kong proxy
    participant US as US API service
    participant Consent as consent-service
    participant Token as token-service
    participant Data as us-data-gateway
    participant Score as scoring-orchestrator
    participant PG as Postgres
    participant Redis as Redis
    participant DNS as DNS
    participant Client as Client

    Ops->>VM: Provision host and install Docker
    Ops->>VM: Start US API and support services
    VM->>PG: Connect using DATABASE_URL
    VM->>Redis: Connect using REDIS_URL
    VM->>US: Run container on port 8080
    VM->>Consent: Run container on port 8081
    VM->>Token: Run container on port 8083
    VM->>Data: Run container on port 8084
    VM->>Score: Run container on port 8082
    Ops->>DNS: Point api.joinlita.com to the new VM
    Client->>Kong: Send production request
    Kong->>US: Route public requests
    Kong->>Consent: Route supporting requests
    Kong->>Token: Route supporting requests
    Kong->>Data: Route supporting requests
    Kong->>Score: Route supporting requests
    Ops->>VM: Decommission old VM after stable monitoring

JP API migration notes

The migration guide includes a JP-specific checklist because the JP API may live in separate service paths.

  1. Locate the JP API service path(s) in the repository.
  2. Build and deploy using the service’s own Docker or runtime instructions.
  3. Mirror the needed infrastructure dependencies.
  4. Validate with the JP API’s smoke tests or API collection.
  5. Cut over DNS or load balancer targets for api.joinlita.com.

Environment Variables and Required Inputs

Files: services/us-api/.env.example, documents/us-jp-api-vm-migration.md

US API template variables

Variable Example value in repo Purpose in deployment
PORT 8080 US API listen port
DATABASE_URL postgresql://user:pass@localhost:5432/us_api PostgreSQL connection string
JWT_PRIVATE_KEY -----BEGIN PRIVATE KEY----- JWT signing material
JWT_PUBLIC_KEY -----BEGIN PUBLIC KEY----- JWT verification material
PARTNER_API_KEYS partner_key_1,partner_key_2,sotheby_partner_token Comma-separated partner credential set
WEBHOOK_SIGNING_SECRET webhook_secret Webhook signature secret
TOKEN_TTL_SECONDS 3600 Access token lifetime
LINK_BASE_URL https://joinlita.com/us Base URL used by the US API deployment template
SCORING_CALLBACK_URL https://example.com Callback endpoint expected by the US API deployment template

Migration prerequisites

Input Source Notes
Postgres connection string Migration guide Required before deploying to the new VM
Redis host and port Migration guide Required before deploying to the new VM
REDIS_URL Migration guide Expected at runtime
PROVIDER Migration guide Expected at runtime
JWT_PRIVATE_KEY Migration guide Shared secret input
JWT_PUBLIC_KEY Migration guide Shared secret input
PARTNER_API_KEYS Migration guide Shared secret input
SCORING_CALLBACK_URL Migration guide Shared runtime input
New VM IP address Migration guide Used for validation and cutover
DNS target for api.joinlita.com Migration guide Final public entrypoint
Firewall and security group rules Migration guide Controls external reachability

Gateway, DNS, and Firewall Planning

[!NOTE] services/us-api/.env.example is the only environment template shown in the repository context. The migration guide adds REDIS_URL and PROVIDER to the cutover checklist, so those values must also be supplied during deployment.

File: documents/us-jp-api-vm-migration.md

The migration guide describes Kong as the public entrypoint for the stack. api.joinlita.com should resolve to the Kong proxy on the new VM, and only Kong should accept inbound internet traffic. The API services themselves should remain on the internal network and continue to reach shared dependencies from the new VM.

Public edge expectations

  • api.joinlita.com is the public DNS name used after cutover
  • Kong receives inbound traffic
  • internal services remain private
  • Postgres and Redis must still be reachable from the application services

Firewall and network planning

  • open only the gateway-facing public port to the internet
  • allow service-to-database and service-to-cache traffic
  • permit internal service calls between the US API service and its supporting services
  • handle client reachability through allowlists, security groups, or VPC peering when needed

Gateway cutover order

  1. Provision and secure the new VM
  2. Deploy the services
  3. Confirm database and cache connectivity
  4. Validate health checks and smoke tests
  5. Update DNS or load balancer targets
  6. Verify that traffic lands on the new VM through Kong
  7. Decommission the old VM after monitoring is stable

Terraform Skeleton

File: infra/terraform/README.md

The Terraform area is documented as a skeleton.

Placeholder scope

Placeholder area Documented status
VPC Placeholder module mentioned in the Terraform README
Postgres Placeholder module mentioned in the Terraform README
Redis Placeholder module mentioned in the Terraform README
gateway Placeholder module mentioned in the Terraform README

[!IMPORTANT] The README states that the infrastructure directory contains placeholders for infrastructure modules, specifically VPC, Postgres, Redis, and gateway.

This means the repository currently documents the intended infrastructure boundaries, but the Terraform README does not describe a completed production IaC implementation.

Validation and Cutover Checklist

File: documents/us-jp-api-vm-migration.md

Validation steps

  • Confirm the US API service responds on its health endpoint.
  • Confirm each dependency service is reachable.
  • Run the Newman's collection against the new VM.
  • Verify the baseUrl and partner token environment values before running the smoke suite.

Cutover checklist

  • All services are running on the new VM
  • Health checks are passing
  • Postman/Newman collection passes
  • DNS or load balancer points to the new VM
  • Monitoring and alerts show no elevated errors
  • Old VM has been decommissioned

Dependencies

Files: documents/us-jp-api-vm-migration.md, services/us-api/.env.example, services/consent-service/Dockerfile, services/scoring-orchestrator/Dockerfile, services/token-service/Dockerfile, services/us-data-gateway/Dockerfile, infra/terraform/README.md

  • Docker-based deployment for the US API image
  • Node runtime for consent-service and scoring-orchestrator
  • Go runtime for token-service and us-data-gateway
  • Postgres
  • Redis
  • Kong as the public gateway
  • DNS and load balancer control for api.joinlita.com
  • firewall and network policy control
  • production secrets and runtime inputs listed in the migration guide and .env.example

Testing Considerations

File: documents/us-jp-api-vm-migration.md

The repository’s migration guide expects a deployment verification pass before traffic cutover.

  • smoke test the service health endpoint
  • run the Newman collection against the new VM
  • confirm internal service reachability
  • validate database and cache connectivity
  • confirm DNS resolution after cutover
  • monitor logs during the transition window

Key Classes Reference

Class Responsibility
us-jp-api-vm-migration.md VM migration runbook, cutover order, and validation steps
us-api.md US API deployment expectations and environment notes
us-api/.env.example US API runtime template variables and default values
terraform/README.md Terraform skeleton and placeholder module scope
consent-service/Dockerfile Container runtime definition for the consent service
scoring-orchestrator/Dockerfile Container runtime definition for the scoring orchestrator
token-service/Dockerfile Container runtime definition for the token service
us-data-gateway/Dockerfile Container runtime definition for the US data gateway