ai-wpa/docs/DEPLOYMENT.md

Deployment Guide

This guide covers various deployment options for the SiliconPin application.

Table of Contents

• Prerequisites
• Environment Configuration
• Docker Deployment
• Platform Deployments
  • Vercel
  • Railway
  • DigitalOcean App Platform
  • AWS ECS
• Database Setup
• SSL/HTTPS Configuration
• Monitoring and Logging
• Troubleshooting

Prerequisites

Before deploying, ensure you have:

• Node.js 18+ installed locally (for building)
• Docker and Docker Compose (for containerized deployment)
• Access to MongoDB database (local, Atlas, or cloud provider)
• Access to Redis instance (local, cloud, or managed service)
• Domain name (for production deployment)
• SSL certificates (for HTTPS)

Environment Configuration

Required Environment Variables

Create a .env.production.local file with the following variables:

# Database (REQUIRED)
MONGODB_URI=mongodb://username:password@host:port/database

# Redis (REQUIRED)
REDIS_URL=redis://username:password@host:port

# Authentication Secrets (REQUIRED - Generate secure random strings)
SESSION_SECRET=your-secure-32-character-session-secret
JWT_SECRET=your-secure-jwt-secret
JWT_REFRESH_SECRET=your-secure-jwt-refresh-secret

# Application
NODE_ENV=production
NEXT_PUBLIC_SITE_URL=https://siliconpin.com

Optional Environment Variables

# Analytics
NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX
NEXT_PUBLIC_PLAUSIBLE_DOMAIN=siliconpin.com

# Email
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password

# File Storage
MINIO_ENDPOINT=your-minio-endpoint
MINIO_ACCESS_KEY=your-access-key
MINIO_SECRET_KEY=your-secret-key
MINIO_BUCKET=your-bucket-name

# Monitoring
SENTRY_DSN=your-sentry-dsn

Generating Secrets

Generate secure secrets using:

# Generate a 32-character secret
openssl rand -base64 32

# Or use Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Docker Deployment

Local Development with Docker

1. Start services only (recommended for development):

   docker-compose -f docker-compose.dev.yml up -d
   yarn dev
   

2. Full containerized development:

   docker-compose -f docker-compose.dev.yml up -d
   

Production Deployment with Docker

1. Build and start all services:

   docker-compose up -d
   

2. Build and start with production profile:

   docker-compose --profile production up -d
   

3. Scale the application:

   docker-compose up -d --scale app=3
   

Docker Commands

# Build the application image
docker build -t siliconpin .

# Run the application container
docker run -p 3006:3006 --env-file .env.production.local siliconpin

# View logs
docker-compose logs -f app

# Execute commands in running container
docker-compose exec app yarn db:seed

# Update and restart services
docker-compose pull && docker-compose up -d

Platform Deployments

Vercel

Vercel is the recommended platform for Next.js applications.

1. Connect your repository to Vercel:

   • Visit vercel.com and import your repository
   • Vercel will automatically detect Next.js configuration

2. Configure environment variables:

   • Go to Project Settings → Environment Variables
   • Add all required environment variables
   • Set NODE_ENV=production

3. Configure build settings:

   # Build Command (default is correct)
   yarn build
   
   # Output Directory (default is correct)
   .next
   
   # Install Command
   yarn install
   

4. Domain configuration:

   • Add your custom domain in Project Settings → Domains
   • Configure DNS to point to Vercel

Railway

Railway provides easy deployment with built-in database services.

1. Install Railway CLI:

   npm install -g @railway/cli
   railway login
   

2. Initialize and deploy:

   railway init
   railway add # Add MongoDB and Redis plugins
   railway up
   

3. Configure environment variables:

   # Set environment variables
   railway variables set SESSION_SECRET=your-secret
   railway variables set JWT_SECRET=your-jwt-secret
   
   # Railway automatically provides DATABASE_URL and REDIS_URL
   

4. Custom domain:

   railway domain # Follow prompts to add custom domain
   

DigitalOcean App Platform

1. Create App Spec (app.yaml):

   name: siliconpin
   services:
     - name: web
       source_dir: /
       github:
         repo: your-username/your-repo
         branch: main
       run_command: yarn start
       build_command: yarn build
       environment_slug: node-js
       instance_count: 1
       instance_size_slug: basic-xxs
       routes:
         - path: /
       envs:
         - key: NODE_ENV
           value: production
         - key: MONGODB_URI
           value: ${db.DATABASE_URL}
         - key: REDIS_URL
           value: ${redis.DATABASE_URL}
   
   databases:
     - name: db
       engine: MONGODB
     - name: redis
       engine: REDIS
   

2. Deploy using CLI:

   doctl apps create --spec app.yaml
   

AWS ECS

1. Create ECR repository:

   aws ecr create-repository --repository-name siliconpin
   

2. Build and push Docker image:

   # Get login token
   aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com
   
   # Build and tag image
   docker build -t siliconpin .
   docker tag siliconpin:latest 123456789012.dkr.ecr.us-east-1.amazonaws.com/siliconpin:latest
   
   # Push image
   docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/siliconpin:latest
   

3. Create ECS task definition and service:

   • Use AWS Console or CLI to create ECS cluster
   • Configure task definition with environment variables
   • Set up Application Load Balancer
   • Configure auto-scaling

Database Setup

MongoDB Atlas (Recommended)

1. Create MongoDB Atlas cluster:

   • Visit mongodb.com/cloud/atlas
   • Create a new cluster
   • Configure network access and database user

2. Get connection string:

   mongodb+srv://username:password@cluster0.mongodb.net/database?retryWrites=true&w=majority
   

3. Seed initial data:

   yarn db:seed
   

Self-hosted MongoDB

1. Install MongoDB:

   # Ubuntu/Debian
   sudo apt-get install mongodb
   
   # macOS
   brew install mongodb-community
   
   # Docker
   docker run -d -p 27017:27017 --name mongodb mongo:7
   

2. Create database and user:

   use siliconpin
   db.createUser({
     user: "app",
     pwd: "secure-password",
     roles: ["readWrite"]
   })
   

Redis Setup

Redis Cloud (Recommended)

1. Create Redis Cloud account:
   • Visit redis.com/redis-enterprise-cloud
   • Create a new database
   • Get connection details

Self-hosted Redis

# Install Redis
sudo apt-get install redis-server

# Or with Docker
docker run -d -p 6379:6379 --name redis redis:7-alpine

# Configure Redis (optional)
# Edit /etc/redis/redis.conf
# Set password: requirepass your-password

SSL/HTTPS Configuration

Automatic SSL (Recommended)

Most platforms provide automatic SSL:

• Vercel: Automatic SSL for all domains
• Railway: Automatic SSL certificates
• DigitalOcean: Managed certificates available

Custom SSL with Nginx

1. Obtain SSL certificates:

   # Using Let's Encrypt
   sudo certbot --nginx -d siliconpin.com
   

2. Configure Nginx:

   server {
       listen 443 ssl http2;
       server_name siliconpin.com;
   
       ssl_certificate /etc/letsencrypt/live/siliconpin.com/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/siliconpin.com/privkey.pem;
   
       location / {
           proxy_pass http://localhost:4023;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection 'upgrade';
           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;
           proxy_cache_bypass $http_upgrade;
       }
   }
   

Monitoring and Logging

Health Checks

The application provides health check endpoints:

• Health Check: GET /api/health
• Readiness Check: HEAD /api/health

Example health check response:

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "uptime": 3600,
  "environment": "production",
  "version": "1.0.0",
  "checks": {
    "database": { "status": "healthy" },
    "redis": { "status": "healthy" }
  },
  "responseTime": 45
}

Logging

Configure application logging:

// lib/logger.ts
import winston from 'winston'

const logger = winston.createLogger({
  level: process.env.LOG_LEVEL || 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.errors({ stack: true }),
    winston.format.json()
  ),
  transports: [
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.File({ filename: 'combined.log' }),
  ],
})

if (process.env.NODE_ENV !== 'production') {
  logger.add(
    new winston.transports.Console({
      format: winston.format.simple(),
    })
  )
}

Error Tracking

Set up Sentry for error tracking:

1. Install Sentry:

   yarn add @sentry/nextjs
   

2. Configure Sentry:

   // sentry.client.config.js
   import * as Sentry from '@sentry/nextjs'
   
   Sentry.init({
     dsn: process.env.SENTRY_DSN,
     environment: process.env.NODE_ENV,
   })
   

Troubleshooting

Common Issues

1. Environment Variables Not Loading:

   # Check if .env files are in correct location
   ls -la .env*
   
   # Verify environment variables are set
   echo $MONGODB_URI
   

2. Database Connection Issues:

   # Test MongoDB connection
   mongosh "mongodb://your-connection-string"
   
   # Check MongoDB Atlas network access
   # Ensure your IP is whitelisted
   

3. Redis Connection Issues:

   # Test Redis connection
   redis-cli -u redis://your-redis-url ping
   
   # Check Redis configuration
   redis-cli config get requirepass
   

4. Build Failures:

   # Clear Next.js cache
   rm -rf .next
   
   # Clear node_modules and reinstall
   rm -rf node_modules
   yarn install
   
   # Check build logs
   yarn build --debug
   

5. Container Issues:

   # Check container logs
   docker-compose logs app
   
   # Rebuild containers
   docker-compose build --no-cache
   
   # Check container resource usage
   docker stats
   

Performance Issues

1. Slow Database Queries:

   • Check MongoDB indexes
   • Enable MongoDB profiling
   • Use MongoDB Compass for query analysis

2. High Memory Usage:

   • Monitor with docker stats
   • Check for memory leaks in logs
   • Consider increasing container memory limits

3. Slow Response Times:

   • Enable Redis caching
   • Optimize images and assets
   • Use CDN for static assets

Security Checklist

• All secrets are generated securely and unique
• Database connections use authentication
• Redis is password-protected
• HTTPS is enabled with valid certificates
• Security headers are configured
• CORS is properly configured
• Rate limiting is implemented
• Input validation is in place
• Dependencies are up to date

Maintenance

Regular Tasks

1. Update Dependencies:

   yarn upgrade
   yarn audit
   

2. Database Maintenance:

   # MongoDB
   mongosh --eval "db.runCommand({compact: 'users'})"
   
   # Redis
   redis-cli BGREWRITEAOF
   

3. Log Rotation:

   # Configure logrotate
   sudo nano /etc/logrotate.d/siliconpin
   

4. Backup:

   # MongoDB backup
   mongodump --uri="mongodb://connection-string" --out=/backup/
   
   # Redis backup
   redis-cli --rdb /backup/dump.rdb
   

This deployment guide covers the most common deployment scenarios. Choose the method that best fits your infrastructure requirements and expertise level.