Deployment

Complete guide to deploying SmartPay 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 SmartPay running locally:

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

# Copy environment file
cp .env.example .env

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

Verify Services

Gateway Health

curl http://localhost:8080/health

Agent Health

curl http://localhost:8000/health

View Logs

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 smartpay

Create ConfigMaps

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

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

Deploy Services

kubectl apply -f deployment/kubernetes/

Verify Deployment

kubectl get pods -n smartpay
kubectl get services -n smartpay

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

Warning

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 smartpay

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

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 smartpay -d olive_db > backup.sql

# Restore
psql -h localhost -U smartpay -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

Warning

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

---

Related

Security Reference

Security configuration details

Troubleshooting

Common issues and solutions