xpeditis2.0/docs/deployment/DEPLOYMENT.md

Xpeditis 2.0 - Deployment Guide

📋 Table of Contents

1. Prerequisites
2. Environment Variables
3. Local Development
4. Database Migrations
5. Docker Deployment
6. Production Deployment
7. CI/CD Pipeline
8. Monitoring Setup
9. Backup & Recovery
10. Troubleshooting

---

Prerequisites

System Requirements

• Node.js: 20.x LTS
• npm: 10.x or higher
• PostgreSQL: 15.x or higher
• Redis: 7.x or higher
• Docker: 24.x (optional, for containerized deployment)
• Docker Compose: 2.x (optional)

Development Tools

# Install Node.js (via nvm recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

# Verify installation
node --version  # Should be 20.x
npm --version   # Should be 10.x

---

Environment Variables

Backend (.env)

Create apps/backend/.env:

# Environment
NODE_ENV=production  # development | production | test

# Server
PORT=4000
API_PREFIX=api/v1

# Frontend URL
FRONTEND_URL=https://app.xpeditis.com

# Database
DATABASE_HOST=your-postgres-host.rds.amazonaws.com
DATABASE_PORT=5432
DATABASE_USER=xpeditis_user
DATABASE_PASSWORD=your-secure-password
DATABASE_NAME=xpeditis_prod
DATABASE_SYNC=false  # NEVER true in production
DATABASE_LOGGING=false

# Redis Cache
REDIS_HOST=your-redis-host.elasticache.amazonaws.com
REDIS_PORT=6379
REDIS_PASSWORD=your-redis-password
REDIS_TLS=true

# JWT Authentication
JWT_SECRET=your-jwt-secret-min-32-characters-long
JWT_ACCESS_EXPIRATION=15m
JWT_REFRESH_SECRET=your-refresh-secret-min-32-characters
JWT_REFRESH_EXPIRATION=7d

# Session
SESSION_SECRET=your-session-secret-min-32-characters

# Email (SMTP)
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASSWORD=your-sendgrid-api-key
SMTP_FROM=noreply@xpeditis.com

# S3 Storage (AWS)
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
S3_BUCKET=xpeditis-documents-prod
S3_ENDPOINT=  # Optional, for MinIO

# Sentry Monitoring
SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
SENTRY_ENVIRONMENT=production
SENTRY_TRACES_SAMPLE_RATE=0.1
SENTRY_PROFILES_SAMPLE_RATE=0.05

# Rate Limiting
RATE_LIMIT_GLOBAL_TTL=60
RATE_LIMIT_GLOBAL_LIMIT=100

# Carrier API Keys (examples)
MAERSK_API_KEY=your-maersk-api-key
MSC_API_KEY=your-msc-api-key
CMA_CGM_API_KEY=your-cma-api-key

# Logging
LOG_LEVEL=info  # debug | info | warn | error

Frontend (.env.local)

Create apps/frontend/.env.local:

# API Configuration
NEXT_PUBLIC_API_URL=https://api.xpeditis.com/api/v1
NEXT_PUBLIC_WS_URL=wss://api.xpeditis.com

# Sentry (Frontend)
NEXT_PUBLIC_SENTRY_DSN=https://your-frontend-sentry-dsn@sentry.io/project-id
NEXT_PUBLIC_SENTRY_ENVIRONMENT=production

# Feature Flags (optional)
NEXT_PUBLIC_ENABLE_ANALYTICS=true
NEXT_PUBLIC_ENABLE_CHAT=false

# Google Analytics (optional)
NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX

Security Best Practices

1. Never commit .env files: Add to .gitignore
2. Use secrets management: AWS Secrets Manager, HashiCorp Vault
3. Rotate secrets regularly: Every 90 days minimum
4. Use strong passwords: Min 32 characters, random
5. Encrypt at rest: Use AWS KMS, GCP KMS

---

Local Development

1. Clone Repository

git clone https://github.com/your-org/xpeditis2.0.git
cd xpeditis2.0

2. Install Dependencies

# Install root dependencies
npm install

# Install backend dependencies
cd apps/backend
npm install

# Install frontend dependencies
cd ../frontend
npm install

cd ../..

3. Setup Local Database

# Using Docker
docker run --name xpeditis-postgres \
  -e POSTGRES_USER=xpeditis_user \
  -e POSTGRES_PASSWORD=dev_password \
  -e POSTGRES_DB=xpeditis_dev \
  -p 5432:5432 \
  -d postgres:15-alpine

# Or install PostgreSQL locally
# macOS: brew install postgresql@15
# Ubuntu: sudo apt install postgresql-15

# Create database
psql -U postgres
CREATE DATABASE xpeditis_dev;
CREATE USER xpeditis_user WITH ENCRYPTED PASSWORD 'dev_password';
GRANT ALL PRIVILEGES ON DATABASE xpeditis_dev TO xpeditis_user;

4. Setup Local Redis

# Using Docker
docker run --name xpeditis-redis \
  -p 6379:6379 \
  -d redis:7-alpine

# Or install Redis locally
# macOS: brew install redis
# Ubuntu: sudo apt install redis-server

5. Run Database Migrations

cd apps/backend

# Run all migrations
npm run migration:run

# Generate new migration (if needed)
npm run migration:generate -- -n MigrationName

# Revert last migration
npm run migration:revert

6. Start Development Servers

# Terminal 1: Backend
cd apps/backend
npm run start:dev

# Terminal 2: Frontend
cd apps/frontend
npm run dev

7. Access Application

• Frontend: http://localhost:3000
• Backend API: http://localhost:4000/api/v1
• API Docs: http://localhost:4000/api/docs

---

Database Migrations

Migration Files Location

apps/backend/src/infrastructure/persistence/typeorm/migrations/

Running Migrations

# Production
npm run migration:run

# Check migration status
npm run migration:show

# Revert last migration (use with caution!)
npm run migration:revert

Creating Migrations

# Generate from entity changes
npm run migration:generate -- -n AddUserProfileFields

# Create empty migration
npm run migration:create -- -n CustomMigration

Migration Best Practices

1. Always test locally first
2. Backup database before production migrations
3. Never edit existing migrations (create new ones)
4. Keep migrations idempotent (safe to run multiple times)
5. Add rollback logic in down() method

---

Docker Deployment

Build Docker Images

# Backend
cd apps/backend
docker build -t xpeditis-backend:latest .

# Frontend
cd ../frontend
docker build -t xpeditis-frontend:latest .

Docker Compose (Full Stack)

Create docker-compose.yml:

version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: xpeditis_user
      POSTGRES_PASSWORD: dev_password
      POSTGRES_DB: xpeditis_dev
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - '5432:5432'

  redis:
    image: redis:7-alpine
    ports:
      - '6379:6379'

  backend:
    image: xpeditis-backend:latest
    depends_on:
      - postgres
      - redis
    env_file:
      - apps/backend/.env
    ports:
      - '4000:4000'

  frontend:
    image: xpeditis-frontend:latest
    depends_on:
      - backend
    env_file:
      - apps/frontend/.env.local
    ports:
      - '3000:3000'

volumes:
  postgres_data:

Run with Docker Compose

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

# Rebuild and restart
docker-compose up -d --build

---

Production Deployment

AWS Deployment (Recommended)

1. Infrastructure Setup (Terraform)

# main.tf (example)
provider "aws" {
  region = "us-east-1"
}

module "vpc" {
  source = "terraform-aws-modules/vpc/aws"
  # ... VPC configuration
}

module "rds" {
  source = "terraform-aws-modules/rds/aws"
  engine = "postgres"
  engine_version = "15.3"
  instance_class = "db.t3.medium"
  allocated_storage = 100
  # ... RDS configuration
}

module "elasticache" {
  source = "terraform-aws-modules/elasticache/aws"
  cluster_id = "xpeditis-redis"
  engine = "redis"
  node_type = "cache.t3.micro"
  # ... ElastiCache configuration
}

module "ecs" {
  source = "terraform-aws-modules/ecs/aws"
  cluster_name = "xpeditis-cluster"
  # ... ECS configuration
}

2. Deploy Backend to ECS

# 1. Build and push Docker image to ECR
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin your-account-id.dkr.ecr.us-east-1.amazonaws.com

docker tag xpeditis-backend:latest your-account-id.dkr.ecr.us-east-1.amazonaws.com/xpeditis-backend:latest
docker push your-account-id.dkr.ecr.us-east-1.amazonaws.com/xpeditis-backend:latest

# 2. Update ECS task definition
aws ecs register-task-definition --cli-input-json file://task-definition.json

# 3. Update ECS service
aws ecs update-service --cluster xpeditis-cluster --service xpeditis-backend --task-definition xpeditis-backend:latest

3. Deploy Frontend to Vercel/Netlify

# Vercel (recommended for Next.js)
npm install -g vercel
cd apps/frontend
vercel --prod

# Or Netlify
npm install -g netlify-cli
cd apps/frontend
npm run build
netlify deploy --prod --dir=out

4. Configure Load Balancer

# Create Application Load Balancer
aws elbv2 create-load-balancer \
  --name xpeditis-alb \
  --subnets subnet-xxx subnet-yyy \
  --security-groups sg-xxx

# Create target group
aws elbv2 create-target-group \
  --name xpeditis-backend-tg \
  --protocol HTTP \
  --port 4000 \
  --vpc-id vpc-xxx

# Register targets
aws elbv2 register-targets \
  --target-group-arn arn:aws:elasticloadbalancing:... \
  --targets Id=i-xxx Id=i-yyy

5. Setup SSL Certificate

# Request certificate from ACM
aws acm request-certificate \
  --domain-name api.xpeditis.com \
  --validation-method DNS

# Add HTTPS listener to ALB
aws elbv2 create-listener \
  --load-balancer-arn arn:aws:elasticloadbalancing:... \
  --protocol HTTPS \
  --port 443 \
  --certificates CertificateArn=arn:aws:acm:... \
  --default-actions Type=forward,TargetGroupArn=arn:...

---

CI/CD Pipeline

GitHub Actions Workflow

Create .github/workflows/deploy.yml:

name: Deploy to Production

on:
  push:
    branches:
      - main

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'

      - name: Install dependencies
        run: |
          cd apps/backend
          npm ci          

      - name: Run tests
        run: |
          cd apps/backend
          npm test          

      - name: Run E2E tests
        run: |
          cd apps/frontend
          npm ci
          npx playwright install
          npm run test:e2e          

  deploy-backend:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v2
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-1

      - name: Login to Amazon ECR
        id: login-ecr
        uses: aws-actions/amazon-ecr-login@v1

      - name: Build and push Docker image
        env:
          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
          ECR_REPOSITORY: xpeditis-backend
          IMAGE_TAG: ${{ github.sha }}
        run: |
          cd apps/backend
          docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .
          docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG          

      - name: Update ECS service
        run: |
          aws ecs update-service \
            --cluster xpeditis-cluster \
            --service xpeditis-backend \
            --force-new-deployment          

  deploy-frontend:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'

      - name: Install Vercel CLI
        run: npm install -g vercel

      - name: Deploy to Vercel
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
        run: |
          cd apps/frontend
          vercel --prod --token=$VERCEL_TOKEN          

---

Monitoring Setup

1. Configure Sentry

// apps/backend/src/main.ts
import { initializeSentry } from './infrastructure/monitoring/sentry.config';

initializeSentry({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
  tracesSampleRate: parseFloat(process.env.SENTRY_TRACES_SAMPLE_RATE || '0.1'),
  profilesSampleRate: parseFloat(process.env.SENTRY_PROFILES_SAMPLE_RATE || '0.05'),
  enabled: process.env.NODE_ENV === 'production',
});

2. Setup CloudWatch (AWS)

# Create log group
aws logs create-log-group --log-group-name /ecs/xpeditis-backend

# Create metric filter
aws logs put-metric-filter \
  --log-group-name /ecs/xpeditis-backend \
  --filter-name ErrorCount \
  --filter-pattern "ERROR" \
  --metric-transformations \
    metricName=ErrorCount,metricNamespace=Xpeditis,metricValue=1

3. Create Alarms

# High error rate alarm
aws cloudwatch put-metric-alarm \
  --alarm-name xpeditis-high-error-rate \
  --alarm-description "Alert when error rate exceeds 5%" \
  --metric-name ErrorCount \
  --namespace Xpeditis \
  --statistic Sum \
  --period 300 \
  --evaluation-periods 2 \
  --threshold 50 \
  --comparison-operator GreaterThanThreshold \
  --alarm-actions arn:aws:sns:us-east-1:xxx:ops-alerts

---

Backup & Recovery

Database Backups

# Automated backups (AWS RDS)
aws rds modify-db-instance \
  --db-instance-identifier xpeditis-prod \
  --backup-retention-period 30 \
  --preferred-backup-window "03:00-04:00"

# Manual snapshot
aws rds create-db-snapshot \
  --db-instance-identifier xpeditis-prod \
  --db-snapshot-identifier xpeditis-manual-snapshot-$(date +%Y%m%d)

# Restore from snapshot
aws rds restore-db-instance-from-db-snapshot \
  --db-instance-identifier xpeditis-restored \
  --db-snapshot-identifier xpeditis-manual-snapshot-20251014

S3 Backups

# Enable versioning
aws s3api put-bucket-versioning \
  --bucket xpeditis-documents-prod \
  --versioning-configuration Status=Enabled

# Enable lifecycle policy (delete old versions after 90 days)
aws s3api put-bucket-lifecycle-configuration \
  --bucket xpeditis-documents-prod \
  --lifecycle-configuration file://lifecycle.json

---

Troubleshooting

Common Issues

1. Database Connection Errors

# Check database status
aws rds describe-db-instances --db-instance-identifier xpeditis-prod

# Check security group rules
aws ec2 describe-security-groups --group-ids sg-xxx

# Test connection from ECS task
aws ecs execute-command \
  --cluster xpeditis-cluster \
  --task task-id \
  --container backend \
  --interactive \
  --command "/bin/sh"

# Inside container:
psql -h your-rds-endpoint -U xpeditis_user -d xpeditis_prod

2. High Memory Usage

# Check ECS task metrics
aws cloudwatch get-metric-statistics \
  --namespace AWS/ECS \
  --metric-name MemoryUtilization \
  --dimensions Name=ServiceName,Value=xpeditis-backend \
  --start-time 2025-10-14T00:00:00Z \
  --end-time 2025-10-14T23:59:59Z \
  --period 3600 \
  --statistics Average

# Increase task memory
aws ecs register-task-definition --cli-input-json file://task-definition.json
# (edit memory from 512 to 1024)

3. Rate Limiting Issues

# Check throttled requests in logs
aws logs filter-log-events \
  --log-group-name /ecs/xpeditis-backend \
  --filter-pattern "ThrottlerException"

# Adjust rate limits in .env
RATE_LIMIT_GLOBAL_LIMIT=200  # Increase from 100

---

Health Checks

Backend Health Endpoint

// apps/backend/src/application/controllers/health.controller.ts
@Get('/health')
async healthCheck() {
  return {
    status: 'ok',
    timestamp: new Date().toISOString(),
    uptime: process.uptime(),
    database: await this.checkDatabase(),
    redis: await this.checkRedis(),
  };
}

ALB Health Check Configuration

aws elbv2 modify-target-group \
  --target-group-arn arn:aws:elasticloadbalancing:... \
  --health-check-path /api/v1/health \
  --health-check-interval-seconds 30 \
  --health-check-timeout-seconds 5 \
  --healthy-threshold-count 2 \
  --unhealthy-threshold-count 3

---

Pre-Launch Checklist

• All environment variables set
• Database migrations run
• SSL certificate configured
• DNS records updated
• Load balancer configured
• Health checks passing
• Monitoring and alerts setup
• Backup strategy tested
• Load testing completed
• Security audit passed
• Documentation complete
• Disaster recovery plan documented
• On-call rotation scheduled

---

Document Version: 1.0.0 Last Updated: October 14, 2025 Author: Xpeditis DevOps Team