qhttpx 2.0.1 → 2.1.0

package/docs/PRODUCTION_DEPLOYMENT.md

@@ -0,0 +1,798 @@
+# QHttpX Production Deployment Guide
+
+**Complete Guide to Deploying QHttpX in Production**
+
+---
+
+## Pre-Deployment Checklist
+
+- [ ] All tests passing (`npm test`)
+- [ ] Zero TypeScript errors (`npm run build`)
+- [ ] No npm security vulnerabilities (`npm audit`)
+- [ ] Environment variables documented
+- [ ] Database migrations applied
+- [ ] Backups scheduled
+- [ ] Monitoring configured
+- [ ] Alerting setup
+- [ ] Logging aggregation ready
+- [ ] Load testing completed
+- [ ] Security review done
+- [ ] Team trained on deployment
+- [ ] Rollback plan documented
+- [ ] Incident response plan ready
+
+---
+
+## Environment Setup
+
+### Environment Variables
+
+Create `.env.production`:
+
+```bash
+# Server
+NODE_ENV=production
+PORT=3000
+WORKERS=4
+
+# Database
+DATABASE_URL=postgresql://user:pass@prod-db:5432/qhttpx_prod
+DB_POOL_MIN=5
+DB_POOL_MAX=20
+
+# Authentication
+JWT_SECRET=your-super-secret-key-min-32-chars
+JWT_EXPIRES_IN=7d
+BCRYPT_ROUNDS=12
+
+# Security
+CORS_ORIGIN=https://example.com,https://www.example.com
+RATE_LIMIT_WINDOW_MS=900000
+RATE_LIMIT_MAX=100
+
+# HTTPS
+TLS_KEY_PATH=/etc/ssl/private/key.pem
+TLS_CERT_PATH=/etc/ssl/certs/cert.pem
+
+# Logging
+LOG_LEVEL=info
+LOG_FORMAT=json
+
+# Monitoring
+SENTRY_DSN=https://xxx@xxx.ingest.sentry.io/123456
+DATADOG_API_KEY=your-datadog-key
+PROMETHEUS_PORT=9090
+
+# Secrets
+VAULT_ADDR=https://vault.example.com
+VAULT_TOKEN=s.xxxxxx
+```
+
+### Environment Validation
+
+```typescript
+// src/env.ts
+import { z } from 'zod';
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']),
+  PORT: z.coerce.number().min(1).max(65535),
+  DATABASE_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32),
+  CORS_ORIGIN: z.string(),
+  TLS_KEY_PATH: z.string().optional(),
+  TLS_CERT_PATH: z.string().optional(),
+  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']),
+  SENTRY_DSN: z.string().url().optional(),
+});
+
+export const env = envSchema.parse(process.env);
+```
+
+---
+
+## Deployment Strategies
+
+### 1. Traditional VPS/EC2 Deployment
+
+#### Initial Setup
+
+```bash
+# SSH into server
+ssh ubuntu@your-server.com
+
+# Update system
+sudo apt update && sudo apt upgrade -y
+
+# Install Node.js 18+
+curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+sudo apt install -y nodejs
+
+# Install PM2 (process manager)
+sudo npm install -g pm2
+
+# Clone repository
+git clone https://github.com/yourusername/qhttpx-app.git
+cd qhttpx-app
+
+# Install dependencies
+npm ci --production
+
+# Build
+npm run build
+```
+
+#### PM2 Configuration
+
+Create `ecosystem.config.js`:
+
+```javascript
+module.exports = {
+  apps: [
+    {
+      name: 'qhttpx-app',
+      script: 'dist/index.js',
+      instances: 4,
+      exec_mode: 'cluster',
+      env: {
+        NODE_ENV: 'production',
+        PORT: 3000,
+      },
+      // Restart if memory exceeds 500MB
+      max_memory_restart: '500M',
+      // Restart crashed apps
+      autorestart: true,
+      // Max restarts before waiting
+      max_restarts: 5,
+      min_uptime: '10s',
+      // Logging
+      out_file: '/var/log/qhttpx/out.log',
+      error_file: '/var/log/qhttpx/error.log',
+      log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
+    },
+  ],
+};
+```
+
+#### Startup
+
+```bash
+# Start with PM2
+pm2 start ecosystem.config.js
+
+# Make it start on reboot
+pm2 startup
+pm2 save
+
+# Monitor
+pm2 monit
+pm2 logs
+```
+
+#### Nginx Reverse Proxy
+
+```nginx
+upstream qhttpx {
+  server 127.0.0.1:3000;
+  server 127.0.0.1:3001;
+  server 127.0.0.1:3002;
+  server 127.0.0.1:3003;
+}
+
+server {
+  listen 443 ssl http2;
+  server_name api.example.com;
+
+  ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem;
+  ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
+  
+  # Strong SSL config
+  ssl_protocols TLSv1.2 TLSv1.3;
+  ssl_ciphers HIGH:!aNULL:!MD5;
+  ssl_prefer_server_ciphers on;
+
+  # Security headers
+  add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
+  add_header X-Content-Type-Options "nosniff" always;
+  add_header X-Frame-Options "DENY" always;
+  add_header X-XSS-Protection "1; mode=block" always;
+
+  # Proxy settings
+  location / {
+    proxy_pass http://qhttpx;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    
+    # WebSocket support
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    
+    # Timeouts
+    proxy_connect_timeout 60s;
+    proxy_send_timeout 60s;
+    proxy_read_timeout 60s;
+  }
+
+  # Health check endpoint
+  location /health {
+    access_log off;
+    proxy_pass http://qhttpx;
+  }
+}
+
+# Redirect HTTP to HTTPS
+server {
+  listen 80;
+  server_name api.example.com;
+  return 301 https://$server_name$request_uri;
+}
+```
+
+#### Certbot for SSL
+
+```bash
+# Install Let's Encrypt
+sudo apt install certbot python3-certbot-nginx
+
+# Get certificate
+sudo certbot certonly --standalone -d api.example.com
+
+# Auto-renewal
+0 12 * * * certbot renew --quiet && nginx -s reload
+```
+
+---
+
+### 2. Docker Deployment
+
+#### Dockerfile
+
+```dockerfile
+# Build stage
+FROM node:18-alpine AS builder
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm ci
+
+COPY . .
+RUN npm run build
+
+# Production stage
+FROM node:18-alpine
+
+WORKDIR /app
+
+# Install dumb-init to handle signals properly
+RUN apk add --no-cache dumb-init
+
+# Copy from builder
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+COPY package*.json ./
+
+# Non-root user
+RUN addgroup -g 1001 -S nodejs && \
+    adduser -S nodejs -u 1001
+
+USER nodejs
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+  CMD node -e "require('http').get('http://localhost:3000/health', (r) => {if (r.statusCode !== 200) throw new Error(r.statusCode)})"
+
+# Use dumb-init to forward signals
+ENTRYPOINT ["dumb-init", "--"]
+
+# Start app
+CMD ["node", "dist/index.js"]
+```
+
+#### docker-compose.yml
+
+```yaml
+version: '3.8'
+
+services:
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      NODE_ENV: production
+      DATABASE_URL: postgresql://user:pass@postgres:5432/qhttpx
+      JWT_SECRET: ${JWT_SECRET}
+    depends_on:
+      postgres:
+        condition: service_healthy
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 5s
+    networks:
+      - qhttpx-network
+
+  postgres:
+    image: postgres:15-alpine
+    environment:
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
+      POSTGRES_DB: qhttpx
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - qhttpx-network
+
+  nginx:
+    image: nginx:alpine
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./nginx.conf:/etc/nginx/nginx.conf:ro
+      - ./ssl:/etc/nginx/ssl:ro
+    depends_on:
+      - app
+    restart: unless-stopped
+    networks:
+      - qhttpx-network
+
+volumes:
+  postgres_data:
+
+networks:
+  qhttpx-network:
+    driver: bridge
+```
+
+#### Build and Deploy
+
+```bash
+# Build image
+docker build -t qhttpx:latest .
+
+# Run with compose
+docker-compose up -d
+
+# Monitor
+docker-compose logs -f app
+
+# Scale
+docker-compose up -d --scale app=4
+```
+
+---
+
+### 3. Kubernetes Deployment
+
+#### Deployment
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: qhttpx-app
+  labels:
+    app: qhttpx
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: qhttpx
+  template:
+    metadata:
+      labels:
+        app: qhttpx
+    spec:
+      containers:
+      - name: qhttpx
+        image: qhttpx:latest
+        imagePullPolicy: Always
+        ports:
+        - name: http
+          containerPort: 3000
+        env:
+        - name: NODE_ENV
+          value: production
+        - name: DATABASE_URL
+          valueFrom:
+            secretKeyRef:
+              name: qhttpx-secrets
+              key: database-url
+        - name: JWT_SECRET
+          valueFrom:
+            secretKeyRef:
+              name: qhttpx-secrets
+              key: jwt-secret
+        livenessProbe:
+          httpGet:
+            path: /health
+            port: 3000
+          initialDelaySeconds: 10
+          periodSeconds: 30
+          timeoutSeconds: 5
+          failureThreshold: 3
+        readinessProbe:
+          httpGet:
+            path: /health
+            port: 3000
+          initialDelaySeconds: 5
+          periodSeconds: 10
+          timeoutSeconds: 5
+        resources:
+          requests:
+            memory: "256Mi"
+            cpu: "250m"
+          limits:
+            memory: "512Mi"
+            cpu: "500m"
+```
+
+#### Service
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: qhttpx-service
+spec:
+  type: LoadBalancer
+  selector:
+    app: qhttpx
+  ports:
+  - name: http
+    port: 80
+    targetPort: 3000
+  - name: https
+    port: 443
+    targetPort: 3000
+```
+
+#### Deploy
+
+```bash
+# Create secrets
+kubectl create secret generic qhttpx-secrets \
+  --from-literal=database-url=$DATABASE_URL \
+  --from-literal=jwt-secret=$JWT_SECRET
+
+# Deploy
+kubectl apply -f deployment.yaml
+kubectl apply -f service.yaml
+
+# Monitor
+kubectl get pods
+kubectl logs -f deployment/qhttpx-app
+kubectl describe service qhttpx-service
+```
+
+---
+
+## Database Migrations
+
+### Migration Script
+
+```typescript
+// scripts/migrate.ts
+import { Pool } from 'pg';
+
+const pool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+});
+
+const migrations = [
+  {
+    name: '001_create_users_table',
+    up: async (client) => {
+      await client.query(`
+        CREATE TABLE users (
+          id SERIAL PRIMARY KEY,
+          email VARCHAR(255) UNIQUE NOT NULL,
+          password VARCHAR(255) NOT NULL,
+          name VARCHAR(255),
+          created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+          updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        )
+      `);
+    },
+    down: async (client) => {
+      await client.query('DROP TABLE users');
+    },
+  },
+];
+
+async function migrate(direction: 'up' | 'down') {
+  const client = await pool.connect();
+  
+  try {
+    // Create migrations table
+    await client.query(`
+      CREATE TABLE IF NOT EXISTS migrations (
+        id SERIAL PRIMARY KEY,
+        name VARCHAR(255) UNIQUE NOT NULL,
+        executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+      )
+    `);
+    
+    for (const migration of migrations) {
+      const executed = await client.query(
+        'SELECT * FROM migrations WHERE name = $1',
+        [migration.name]
+      );
+      
+      if (direction === 'up' && executed.rows.length === 0) {
+        console.log(`Running: ${migration.name}`);
+        await migration.up(client);
+        await client.query(
+          'INSERT INTO migrations (name) VALUES ($1)',
+          [migration.name]
+        );
+      } else if (direction === 'down' && executed.rows.length > 0) {
+        console.log(`Rolling back: ${migration.name}`);
+        await migration.down(client);
+        await client.query(
+          'DELETE FROM migrations WHERE name = $1',
+          [migration.name]
+        );
+      }
+    }
+    
+    console.log('Done!');
+  } finally {
+    await client.end();
+  }
+}
+
+const direction = process.argv[2] as 'up' | 'down' || 'up';
+migrate(direction).catch(console.error);
+```
+
+#### Run Migrations
+
+```bash
+# Run migrations before deployment
+npm run migrate:up
+
+# Test rollback
+npm run migrate:down
+
+# Run migrations again
+npm run migrate:up
+```
+
+---
+
+## Monitoring & Observability
+
+### Health Check Endpoint
+
+```typescript
+app.get('/health', ({ json }) => {
+  json({
+    status: 'healthy',
+    uptime: process.uptime(),
+    timestamp: new Date().toISOString(),
+  }, 200);
+});
+
+app.get('/readiness', ({ json, db }) => {
+  try {
+    // Test database
+    await db?.query('SELECT 1');
+    json({ ready: true }, 200);
+  } catch {
+    json({ ready: false }, 503);
+  }
+});
+```
+
+### Metrics Endpoint
+
+```typescript
+import client from 'prom-client';
+
+app.get('/metrics', ({ send }) => {
+  const metrics = client.register.metrics();
+  send(metrics, 200);
+});
+```
+
+### Logging Aggregation
+
+```typescript
+import pino from 'pino';
+
+const logger = pino({
+  transport: {
+    target: 'pino-loki',
+    options: {
+      host: 'logs-server.example.com',
+      basicAuth: process.env.LOKI_AUTH,
+    },
+  },
+});
+
+app.use(async ({ req, next }) => {
+  logger.info({ method: req.method, path: req.url });
+  if (next) await next();
+});
+```
+
+### Error Tracking
+
+```typescript
+import * as Sentry from "@sentry/node";
+
+Sentry.init({
+  dsn: process.env.SENTRY_DSN,
+  environment: process.env.NODE_ENV,
+  tracesSampleRate: 0.1,
+});
+
+app.onError(({ error, json }) => {
+  Sentry.captureException(error);
+  json({ error: 'Internal server error' }, 500);
+});
+```
+
+---
+
+## Performance Tuning
+
+### Node.js Flags
+
+```bash
+# Increase memory limit
+node --max-old-space-size=4096 dist/index.js
+
+# Enable profiling
+node --prof dist/index.js
+node --prof-process isolate-*.log > profile.txt
+```
+
+### PM2 Cluster Mode
+
+```javascript
+module.exports = {
+  apps: [
+    {
+      name: 'qhttpx',
+      script: 'dist/index.js',
+      instances: 'max',  // Use all CPU cores
+      exec_mode: 'cluster',
+      merge_logs: true,
+    },
+  ],
+};
+```
+
+---
+
+## Backup & Disaster Recovery
+
+### Database Backups
+
+```bash
+# Daily backup
+0 2 * * * pg_dump $DATABASE_URL > /backups/db-$(date +%Y%m%d).sql
+
+# Weekly full backup to S3
+0 3 * * 0 pg_dump $DATABASE_URL | gzip | aws s3 cp - s3://backups/db-$(date +%Y%m%d).sql.gz
+```
+
+### Restore from Backup
+
+```bash
+# From local backup
+psql $DATABASE_URL < /backups/db-20240121.sql
+
+# From S3 backup
+aws s3 cp s3://backups/db-20240121.sql.gz - | gunzip | psql $DATABASE_URL
+```
+
+---
+
+## Rollback Procedure
+
+```bash
+# Tag release
+git tag v1.0.0
+
+# If something goes wrong
+git checkout v0.9.9
+npm install
+npm run build
+
+# Restart with PM2
+pm2 restart qhttpx
+```
+
+---
+
+## Post-Deployment Checklist
+
+- [ ] Server responding to health checks
+- [ ] Database connections working
+- [ ] Logging aggregation receiving logs
+- [ ] Monitoring collecting metrics
+- [ ] Alerting configured and tested
+- [ ] SSL certificate valid
+- [ ] All endpoints tested
+- [ ] Performance acceptable
+- [ ] Load testing completed
+- [ ] Security scan passed
+- [ ] Team notified of deployment
+- [ ] Documentation updated
+- [ ] Rollback plan confirmed
+
+---
+
+## Troubleshooting
+
+### High Memory Usage
+
+```bash
+# Check memory
+ps aux | grep node
+
+# Profile memory
+node --inspect dist/index.js
+# Then open chrome://inspect in Chrome DevTools
+
+# Check for memory leaks
+npm install clinic
+clinic doctor -- node dist/index.js
+```
+
+### Database Connection Issues
+
+```bash
+# Test connection
+psql $DATABASE_URL
+
+# Check pool status
+app.get('/debug/db', ({ json }) => {
+  json({
+    poolSize: pool.totalCount,
+    idle: pool.idleCount,
+    waiting: pool.waitingCount,
+  });
+});
+```
+
+### High Latency
+
+```bash
+# Check slow endpoints
+app.use(async ({ path, next }) => {
+  const start = Date.now();
+  if (next) await next();
+  const duration = Date.now() - start;
+  if (duration > 1000) {
+    console.warn(`Slow: ${path} (${duration}ms)`);
+  }
+});
+```
+
+---
+
+## Support
+
+For deployment issues:
+1. Check logs: `pm2 logs` or `kubectl logs`
+2. Check metrics: Visit `/metrics` endpoint
+3. Check health: Visit `/health` endpoint
+4. Read security guide: `docs/SECURITY.md`
+5. Consult API reference: `docs/API_REFERENCE.md`