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:

```bash
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:

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

Or using the virtual-banker specific compose file:

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

### 3. Verify

Check health:

```bash
curl http://localhost:8081/health
```

Access widget:

```
http://localhost:8082
```

## Production Deployment

### Environment Variables

**Backend API:**
```bash
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

```yaml
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:

```yaml
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