Skip to main content

​
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

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

​
Manual Setup

For development without Docker:
1

Start Wallet-Core

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

Start Gateway

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

Start Agent-TS

cd agent-ts
npm install
npm run dev

​
Production Deployment

​
Kubernetes

1

Create Namespace

kubectl apply -f deployment/kubernetes/namespace.yaml
2

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
3

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
4

Deploy Services

kubectl apply -f deployment/kubernetes/
5

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

VariableServiceDescription
DATABASE_URLAllPostgreSQL connection string
JWT_SECRETGatewayJWT signing secret (32+ chars)
OPENAI_API_KEYAgent-TSOpenAI API key
GATEWAY_API_KEYAgent-TSInternal service key

​
Optional Variables

VariableServiceDefaultDescription
PORTAll8080/8000/50051Service port
LOG_LEVELAllinfoLogging level
WALLET_CORE_ADDRESSGatewaylocalhost:50051Wallet-Core gRPC address
AWS_S3_BUCKET_NAMEAgent-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

ServiceEndpointProtocol
GatewayGET /healthHTTP
Agent-TSGET /healthHTTP
Wallet-CoregRPC HealthgRPC

​
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:
ServiceEndpoint
Gatewayhttp://gateway:9090/metrics
Wallet-Corehttp://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

TypeFrequencyRetention
Full backupDaily30 days
Transaction logsContinuous7 days
Point-in-timeEnabled24 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