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, andscoring-orchestratoras 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_URLREDIS_URLJWT_PRIVATE_KEYJWT_PUBLIC_KEYPARTNER_API_KEYSPROVIDERSCORING_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 runexample 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-servicetoken-serviceus-data-gatewayscoring-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.
- Locate the JP API service path(s) in the repository.
- Build and deploy using the service’s own Docker or runtime instructions.
- Mirror the needed infrastructure dependencies.
- Validate with the JP API’s smoke tests or API collection.
- 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.exampleis the only environment template shown in the repository context. The migration guide addsREDIS_URLandPROVIDERto 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.comis 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
- Provision and secure the new VM
- Deploy the services
- Confirm database and cache connectivity
- Validate health checks and smoke tests
- Update DNS or load balancer targets
- Verify that traffic lands on the new VM through Kong
- 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, andgateway.
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
baseUrland 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-serviceandscoring-orchestrator - Go runtime for
token-serviceandus-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 |