virtual-banker/docs/DEPLOYMENT.md

Deployment Guide

Prerequisites

• Docker and Docker Compose
• PostgreSQL 16+ with pgvector extension
• Redis 7+
• (Optional) Kubernetes cluster for production

Development Deployment

1. Database Setup

Run migrations:

cd virtual-banker/database
psql -U explorer -d explorer -f migrations/001_sessions.up.sql
psql -U explorer -d explorer -f migrations/002_conversations.up.sql
psql -U explorer -d explorer -f migrations/003_tenants.up.sql
psql -U explorer -d explorer -f migrations/004_vector_extension.up.sql

2. Start Services

Using the main docker-compose.yml:

cd deployment
docker-compose up -d virtual-banker-api virtual-banker-widget

Or using the virtual-banker specific compose file:

cd virtual-banker/deployment
docker-compose up -d

3. Verify

Check health:

curl http://localhost:8081/health

Access widget:

http://localhost:8082

Production Deployment

Environment Variables

Backend API:

DATABASE_URL=postgres://user:pass@host:5432/db
REDIS_URL=redis://host:6379
PORT=8081

Widget CDN:

• Deploy to CDN (Cloudflare, AWS CloudFront, etc.)
• Configure CORS headers
• Enable gzip compression

Docker Compose Production

services:
  virtual-banker-api:
    image: your-registry/virtual-banker-api:latest
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=${REDIS_URL}
    deploy:
      replicas: 3
      resources:
        limits:
          cpus: '2'
          memory: 2G

Kubernetes Deployment

Example deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: virtual-banker-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: virtual-banker-api
  template:
    metadata:
      labels:
        app: virtual-banker-api
    spec:
      containers:
      - name: api
        image: your-registry/virtual-banker-api:latest
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: virtual-banker-secrets
              key: database-url
        ports:
        - containerPort: 8081
        resources:
          requests:
            memory: "1Gi"
            cpu: "1"
          limits:
            memory: "2Gi"
            cpu: "2"

Scaling

Horizontal Scaling

• API Service: Stateless, scale horizontally
• Widget CDN: Use CDN for global distribution
• Avatar Renderer: GPU-bound, scale based on concurrent sessions

Vertical Scaling

• Database: Increase connection pool, add read replicas
• Redis: Use Redis Cluster for high availability
• Avatar Renderer: Allocate more GPU resources

Monitoring

Health Checks

• API: GET /health
• Widget: GET /health (nginx)

Metrics

• Session creation rate
• Active sessions
• API latency
• Error rates
• Avatar render queue

Logging

• Structured logging (JSON)
• Log aggregation (ELK, Loki, etc.)
• Audit logs for compliance

Security

Network

• Use internal networks for service communication
• Expose only necessary ports
• Use TLS for external communication

Secrets

• Store secrets in secret management (Vault, AWS Secrets Manager)
• Rotate tokens regularly
• Use ephemeral tokens for sessions

Compliance

• Enable audit logging
• Implement data retention policies
• PII redaction in logs
• Encryption at rest and in transit

Backup & Recovery

Database

• Regular PostgreSQL backups
• Point-in-time recovery
• Test restore procedures

Redis

• Enable persistence (AOF/RDB)
• Regular snapshots

Troubleshooting

Common Issues

Session creation fails:

• Check database connection
• Verify tenant exists
• Check JWT validation

Widget not loading:

• Check CORS configuration
• Verify CDN is accessible
• Check browser console for errors

Avatar not displaying:

• Verify WebRTC connection
• Check avatar renderer service
• Verify GPU resources available