# Deployment Guide

This guide provides detailed instructions for deploying the Playwright Web Proxy in various environments.

## Table of Contents

- [Prerequisites](#prerequisites)
- [Development Deployment](#development-deployment)
- [Docker Deployment](#docker-deployment)
- [Kubernetes Deployment](#kubernetes-deployment)
- [Production Checklist](#production-checklist)
- [Scaling Guide](#scaling-guide)
- [Monitoring Setup](#monitoring-setup)
- [Backup & Recovery](#backup--recovery)

## Prerequisites

### Minimum Requirements
- Node.js 18+
- 4GB RAM minimum (16GB+ recommended for production)
- 4 CPU cores minimum (8+ recommended for production)
- 20GB disk space

### For Docker Deployment
- Docker 20.10+
- Docker Compose 2.0+

### For Kubernetes Deployment
- Kubernetes 1.24+
- Helm 3.8+
- kubectl configured
- Ingress controller (nginx recommended)
- Cert-manager (for TLS)

## Development Deployment

### Local Setup

1. **Install dependencies:**
   ```bash
   npm install
   cd client && npm install && cd ..
   ```

2. **Install Playwright browsers:**
   ```bash
   npx playwright install chromium
   npx playwright install-deps chromium
   ```

3. **Create environment file:**
   ```bash
   cp .env.example .env
   ```

4. **Edit .env file:**
   ```env
   PORT=3000
   NODE_ENV=development
   SESSION_SECRET=dev-secret-change-in-production
   JWT_SECRET=dev-jwt-secret-change-in-production
   MAX_CONCURRENT_SESSIONS=10
   ```

5. **Start Redis (optional, but recommended):**
   ```bash
   docker run -d -p 6379:6379 redis:7-alpine
   ```

6. **Start backend:**
   ```bash
   npm run dev
   ```

7. **Start frontend (separate terminal):**
   ```bash
   cd client
   npm run dev
   ```

8. **Access the application:**
   - Frontend: http://localhost:3001
   - Backend: http://localhost:3000
   - Metrics: http://localhost:3000/metrics

## Docker Deployment

### Single Container (Quick Start)

1. **Build the image:**
   ```bash
   docker build -t playwright-proxy:latest .
   ```

2. **Run the container:**
   ```bash
   docker run -d \
     --name playwright-proxy \
     -p 3000:3000 \
     -p 3001:3001 \
     -e SESSION_SECRET=your-secret-key \
     -e JWT_SECRET=your-jwt-secret \
     -e MAX_CONCURRENT_SESSIONS=50 \
     --shm-size=2g \
     playwright-proxy:latest
   ```

   **Note:** `--shm-size=2g` is important for Chrome to function properly.

### Docker Compose (Recommended)

1. **Create environment file:**
   ```bash
   cp .env.example .env
   ```

2. **Edit .env with production values:**
   ```env
   SESSION_SECRET=generate-strong-random-string
   JWT_SECRET=generate-strong-random-string
   GRAFANA_PASSWORD=secure-grafana-password
   ```

3. **Start all services:**
   ```bash
   docker-compose up -d
   ```

4. **View logs:**
   ```bash
   docker-compose logs -f proxy
   ```

5. **Start with monitoring:**
   ```bash
   docker-compose --profile monitoring up -d
   ```

6. **Check service health:**
   ```bash
   curl http://localhost:3000/health
   ```

### Docker Compose Production Configuration

Create `docker-compose.prod.yml`:

```yaml
version: '3.8'

services:
  redis:
    image: redis:7-alpine
    command: redis-server --requirepass ${REDIS_PASSWORD}
    volumes:
      - redis-data:/data
    restart: always

  proxy:
    image: playwright-proxy:latest
    environment:
      - NODE_ENV=production
      - SESSION_SECRET=${SESSION_SECRET}
      - JWT_SECRET=${JWT_SECRET}
      - REDIS_URL=redis://:${REDIS_PASSWORD}@redis:6379
      - MAX_CONCURRENT_SESSIONS=200
    deploy:
      replicas: 3
      resources:
        limits:
          cpus: '4'
          memory: 4G
        reservations:
          cpus: '2'
          memory: 2G
    restart: always
```

Deploy with:
```bash
docker-compose -f docker-compose.prod.yml up -d
```

## Kubernetes Deployment

### Quick Start

1. **Create namespace:**
   ```bash
   kubectl create namespace playwright-proxy
   ```

2. **Create secrets:**
   ```bash
   kubectl create secret generic playwright-proxy-secrets \
     --from-literal=session-secret=$(openssl rand -base64 32) \
     --from-literal=jwt-secret=$(openssl rand -base64 32) \
     --from-literal=redis-password=$(openssl rand -base64 32) \
     -n playwright-proxy
   ```

3. **Install with Helm:**
   ```bash
   helm install playwright-proxy ./helm/playwright-proxy \
     --namespace playwright-proxy \
     --set secrets.sessionSecret=$(kubectl get secret playwright-proxy-secrets -n playwright-proxy -o jsonpath='{.data.session-secret}') \
     --set secrets.jwtSecret=$(kubectl get secret playwright-proxy-secrets -n playwright-proxy -o jsonpath='{.data.jwt-secret}') \
     --set redis.auth.password=$(kubectl get secret playwright-proxy-secrets -n playwright-proxy -o jsonpath='{.data.redis-password}')
   ```

### Production Deployment

1. **Create production values file (`values-prod.yaml`):**

```yaml
replicaCount: 3

image:
  repository: your-registry/playwright-proxy
  tag: "1.0.0"
  pullPolicy: IfNotPresent

resources:
  limits:
    cpu: 4000m
    memory: 4Gi
  requests:
    cpu: 2000m
    memory: 2Gi

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70
  targetMemoryUtilizationPercentage: 80

config:
  nodeEnv: production
  maxConcurrentSessions: 200
  browserTimeout: 300000
  idleTimeout: 600000

redis:
  enabled: true
  architecture: standalone
  auth:
    enabled: true
  master:
    persistence:
      enabled: true
      size: 10Gi
      storageClass: "fast-ssd"

ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
    nginx.ingress.kubernetes.io/proxy-body-size: "10m"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "300"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "300"
  hosts:
    - host: proxy.yourdomain.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: playwright-proxy-tls
      hosts:
        - proxy.yourdomain.com

monitoring:
  enabled: true
  prometheus:
    enabled: true
```

2. **Deploy with custom values:**
   ```bash
   helm upgrade --install playwright-proxy ./helm/playwright-proxy \
     --namespace playwright-proxy \
     -f values-prod.yaml \
     --wait \
     --timeout 10m
   ```

3. **Verify deployment:**
   ```bash
   kubectl get pods -n playwright-proxy
   kubectl get services -n playwright-proxy
   kubectl get ingress -n playwright-proxy
   ```

4. **Check logs:**
   ```bash
   kubectl logs -f deployment/playwright-proxy -n playwright-proxy
   ```

### Setting up TLS/HTTPS

1. **Install cert-manager:**
   ```bash
   kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml
   ```

2. **Create ClusterIssuer:**

```yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: your-email@example.com
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
    - http01:
        ingress:
          class: nginx
```

Apply:
```bash
kubectl apply -f cluster-issuer.yaml
```

### Load Balancing Strategy

For optimal performance with 200 concurrent users:

1. **Session Affinity:**
   Update ingress annotations:
   ```yaml
   nginx.ingress.kubernetes.io/affinity: "cookie"
   nginx.ingress.kubernetes.io/session-cookie-name: "proxy-session"
   nginx.ingress.kubernetes.io/session-cookie-expires: "3600"
   ```

2. **WebSocket Support:**
   ```yaml
   nginx.ingress.kubernetes.io/websocket-services: "playwright-proxy"
   nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
   ```

## Production Checklist

### Security

- [ ] Change all default secrets
- [ ] Enable HTTPS/TLS
- [ ] Configure CORS properly
- [ ] Set up firewall rules
- [ ] Enable Redis authentication
- [ ] Implement proper user management
- [ ] Set up regular security audits
- [ ] Enable audit logging

### Performance

- [ ] Configure resource limits
- [ ] Enable horizontal pod autoscaling
- [ ] Set up Redis persistence
- [ ] Configure appropriate timeouts
- [ ] Enable compression
- [ ] Optimize browser pool size

### Monitoring

- [ ] Set up Prometheus scraping
- [ ] Configure Grafana dashboards
- [ ] Set up alerting rules
- [ ] Enable log aggregation
- [ ] Monitor resource usage
- [ ] Track error rates

### Reliability

- [ ] Configure health checks
- [ ] Set up liveness/readiness probes
- [ ] Enable automatic restarts
- [ ] Configure pod disruption budgets
- [ ] Set up backup strategy
- [ ] Test disaster recovery

## Scaling Guide

### Vertical Scaling (Single Instance)

Increase resources for a single pod:

```yaml
resources:
  limits:
    cpu: 8000m
    memory: 8Gi
  requests:
    cpu: 4000m
    memory: 4Gi

config:
  maxConcurrentSessions: 400
```

### Horizontal Scaling (Multiple Instances)

**For 200 concurrent users:**

- **3 pods** @ 2 CPU, 2GB RAM each (66 sessions/pod)
- **5 pods** @ 2 CPU, 2GB RAM each (40 sessions/pod) - Recommended

**For 500 concurrent users:**

- **5 pods** @ 4 CPU, 4GB RAM each (100 sessions/pod)
- **10 pods** @ 2 CPU, 2GB RAM each (50 sessions/pod)

**Configure HPA:**

```yaml
autoscaling:
  enabled: true
  minReplicas: 5
  maxReplicas: 15
  targetCPUUtilizationPercentage: 70
  targetMemoryUtilizationPercentage: 75
```

### Database Scaling (Redis)

For high-availability:

```yaml
redis:
  architecture: replication
  auth:
    enabled: true
  replica:
    replicaCount: 2
  sentinel:
    enabled: true
  persistence:
    enabled: true
    size: 20Gi
```

## Monitoring Setup

### Prometheus

1. **Verify metrics endpoint:**
   ```bash
   curl http://localhost:3000/metrics
   ```

2. **Configure Prometheus scraping:**

```yaml
scrape_configs:
  - job_name: 'playwright-proxy'
    kubernetes_sd_configs:
      - role: pod
        namespaces:
          names:
            - playwright-proxy
    relabel_configs:
      - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
        action: keep
        regex: true
      - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_port]
        action: replace
        target_label: __address__
        regex: ([^:]+)(?::\d+)?;(\d+)
        replacement: $1:$2
```

### Grafana Dashboards

Import the provided dashboard or create custom panels:

**Key Metrics to Monitor:**
- Active sessions
- Session creation rate
- Navigation success rate
- WebSocket connections
- CPU/Memory usage
- Error rates

### Alerting Rules

Create `alerts.yaml`:

```yaml
groups:
  - name: playwright-proxy
    interval: 30s
    rules:
      - alert: HighErrorRate
        expr: rate(proxy_navigations_total{status="error"}[5m]) > 0.1
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "High navigation error rate"

      - alert: PoolAtCapacity
        expr: proxy_sessions_active >= 200
        for: 2m
        labels:
          severity: warning
        annotations:
          summary: "Browser pool at capacity"

      - alert: HighMemoryUsage
        expr: container_memory_usage_bytes{pod=~"playwright-proxy.*"} / container_spec_memory_limit_bytes > 0.9
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "High memory usage detected"
```

## Backup & Recovery

### Backup Strategy

1. **Redis Data:**
   ```bash
   kubectl exec -it redis-pod -n playwright-proxy -- redis-cli BGSAVE
   ```

2. **Configuration:**
   ```bash
   helm get values playwright-proxy -n playwright-proxy > backup-values.yaml
   kubectl get secret -n playwright-proxy -o yaml > backup-secrets.yaml
   ```

3. **Logs:**
   ```bash
   kubectl logs deployment/playwright-proxy -n playwright-proxy > backup-logs.txt
   ```

### Disaster Recovery

1. **Restore from backup:**
   ```bash
   helm upgrade playwright-proxy ./helm/playwright-proxy \
     -f backup-values.yaml \
     --namespace playwright-proxy
   ```

2. **Restore secrets:**
   ```bash
   kubectl apply -f backup-secrets.yaml
   ```

3. **Verify deployment:**
   ```bash
   kubectl get pods -n playwright-proxy
   curl http://proxy.yourdomain.com/health
   ```

## Troubleshooting

### Pod Crashes

```bash
kubectl describe pod <pod-name> -n playwright-proxy
kubectl logs <pod-name> -n playwright-proxy --previous
```

### OOM (Out of Memory)

Increase memory limits or reduce `MAX_CONCURRENT_SESSIONS`

### Network Issues

Check ingress and service configuration:
```bash
kubectl get ingress -n playwright-proxy
kubectl describe service playwright-proxy -n playwright-proxy
```

### Performance Issues

1. Check resource usage:
   ```bash
   kubectl top pods -n playwright-proxy
   ```

2. Review metrics in Grafana
3. Check HPA status:
   ```bash
   kubectl get hpa -n playwright-proxy
   ```

## Support

For deployment issues:
- Check application logs
- Review Kubernetes events
- Consult the main README
- Open a GitHub issue