Deployment Reference

Complete guide to deploying OLIVE in development, staging, and production environments.

Prerequisites

Docker

Docker 20.10+ and Docker Compose v2

Go

Go 1.21+ (for local builds)

Node.js

Node.js 18+ (for Agent-TS)

Local Development

Docker Compose (Recommended)

The fastest way to get OLIVE running locally:

# Clone the repository
git clone https://github.com/EmmanuelKeifala/olive.git
cd olive

# Copy environment file
cp .env.example .env

# Start all services
docker compose up -d --build gateway wallet-core agent

Verify Services

curl http://localhost:8080/health

curl http://localhost:8000/health

docker compose logs -f gateway wallet-core agent

Manual Setup

For development without Docker:

Start Wallet-Core

cd wallet-core
go run cmd/server/main.go -config config.yaml

Start Gateway

cd gateway
go run cmd/server/main.go -config config.yaml

Start Agent-TS

cd agent-ts
npm install
npm run dev

Production Deployment

Kubernetes

Create Namespace

kubectl apply -f deployment/kubernetes/namespace.yaml

Create TLS Secrets

./scripts/generate-certs.sh

kubectl create secret generic wallet-core-certs \
  --from-file=certs/wallet-core.crt \
  --from-file=certs/wallet-core.key \
  --from-file=certs/ca.crt \
  -n olive

Create ConfigMaps

kubectl create configmap wallet-core-config \
  --from-file=wallet-core/config.production.yaml \
  -n olive

kubectl create configmap gateway-config \
  --from-file=gateway/config.production.yaml \
  -n olive

Deploy Services

kubectl apply -f deployment/kubernetes/

Verify Deployment

kubectl get pods -n olive
kubectl get services -n olive

Render (Cloud)

Deploy using the included render.yaml:

# Push to GitHub and connect to Render
# render.yaml configures services automatically

Environment Variables

Required Variables

Variable	Service	Description
`DATABASE_URL`	All	PostgreSQL connection string
`JWT_SECRET`	Gateway	JWT signing secret (32+ chars)
`OPENAI_API_KEY`	Agent-TS	OpenAI API key
`GATEWAY_API_KEY`	Agent-TS	Internal service key

Optional Variables

Variable	Service	Default	Description
`PORT`	All	8080/8000/50051	Service port
`LOG_LEVEL`	All	`info`	Logging level
`WALLET_CORE_ADDRESS`	Gateway	`localhost:50051`	Wallet-Core gRPC address
`AWS_S3_BUCKET_NAME`	Agent-TS	-	KYC document storage

Never commit secrets to version control. Use environment variables or a secrets manager.

TLS/mTLS Configuration

Enable TLS on Wallet-Core

# wallet-core/config.production.yaml
tls:
  enabled: true
  cert_file: /certs/wallet-core.crt
  key_file: /certs/wallet-core.key
  ca_file: /certs/ca.crt

Enable TLS on Gateway

# gateway/config.production.yaml
tls:
  enabled: true
  cert_file: /certs/gateway.crt
  key_file: /certs/gateway.key
  
wallet_core:
  address: wallet-core:50051
  use_tls: true
  tls_cert_path: /certs/ca.crt

Generate Certificates

# Use the provided script
./scripts/generate-certs.sh

# Or use your own CA
openssl req -x509 -newkey rsa:4096 \
  -keyout ca.key -out ca.crt \
  -days 365 -nodes

Health Checks

Service	Endpoint	Protocol
Gateway	`GET /health`	HTTP
Agent-TS	`GET /health`	HTTP
Wallet-Core	gRPC Health	gRPC

Health Check Response

{
  "service": "gateway",
  "version": "1.0.0",
  "healthy": true,
  "wallet_core": {
    "healthy": true,
    "version": "1.0.0"
  }
}

Scaling

Horizontal Scaling

# Scale Gateway (stateless - unlimited)
kubectl scale deployment gateway --replicas=5 -n olive

# Scale Agent-TS (stateless - unlimited)
kubectl scale deployment agent --replicas=3 -n olive

Resource Limits

# Kubernetes deployment
resources:
  requests:
    memory: "512Mi"
    cpu: "500m"
  limits:
    memory: "1Gi"
    cpu: "1000m"

Database Scaling

Use connection pooling (PgBouncer)
Add read replicas for queries
Consider sharding for high write volume

Monitoring

Prometheus Metrics

All services expose Prometheus-compatible metrics:

Service	Endpoint
Gateway	`http://gateway:9090/metrics`
Wallet-Core	`http://wallet-core:9091/metrics`

Key Metrics

http_requests_total - Request count by status
http_request_duration_seconds - Latency histogram
grpc_server_handled_total - gRPC call count
wallet_transactions_total - Transaction count

Backup and Recovery

Database Backup

# PostgreSQL backup
pg_dump -h localhost -U olive -d olive_db > backup.sql

# Restore
psql -h localhost -U olive -d olive_db < backup.sql

Backup Schedule

Type	Frequency	Retention
Full backup	Daily	30 days
Transaction logs	Continuous	7 days
Point-in-time	Enabled	24 hours

Security Checklist

Complete this checklist before production deployment.

TLS/mTLS enabled on all services
Strong JWT secrets configured (32+ chars)
Rate limiting enabled and tuned
Database encrypted (at-rest and in-transit)
Audit logging enabled
Firewall rules configured
Network policies in Kubernetes
Regular backups configured
Monitoring and alerting active

Security Reference

Security configuration details

Troubleshooting

Common issues and solutions

​Deployment Reference

​Prerequisites

Docker

Go

Node.js

​Local Development

​Docker Compose (Recommended)

​Verify Services

​Manual Setup

​Production Deployment

​Kubernetes

​Render (Cloud)

​Environment Variables

​Required Variables

​Optional Variables

​TLS/mTLS Configuration

​Enable TLS on Wallet-Core

​Enable TLS on Gateway

​Generate Certificates

​Health Checks

​Health Check Response

​Scaling

​Horizontal Scaling

​Resource Limits

​Database Scaling

​Monitoring

​Prometheus Metrics

​Key Metrics

​Backup and Recovery

​Database Backup

​Backup Schedule

​Security Checklist

​Related

Security Reference

Troubleshooting

Deployment Reference

Prerequisites

Local Development

Docker Compose (Recommended)

Verify Services

Manual Setup

Production Deployment

Kubernetes

Render (Cloud)

Environment Variables

Required Variables

Optional Variables

TLS/mTLS Configuration

Enable TLS on Wallet-Core

Enable TLS on Gateway

Generate Certificates

Health Checks

Health Check Response

Scaling

Horizontal Scaling

Resource Limits

Database Scaling

Monitoring

Prometheus Metrics

Key Metrics

Backup and Recovery

Database Backup

Backup Schedule

Security Checklist

Related