mockupAWS/docs/DEPLOYMENT-GUIDE.md

# mockupAWS Production Deployment Guide

> **Version:** 1.0.0  
> **Last Updated:** 2026-04-07  
> **Status:** Production Ready

---

## Table of Contents

1. [Overview](#overview)
2. [Prerequisites](#prerequisites)
3. [Deployment Options](#deployment-options)
4. [Infrastructure as Code](#infrastructure-as-code)
5. [CI/CD Pipeline](#cicd-pipeline)
6. [Environment Configuration](#environment-configuration)
7. [Security Considerations](#security-considerations)
8. [Troubleshooting](#troubleshooting)
9. [Rollback Procedures](#rollback-procedures)

---

## Overview

This guide covers deploying mockupAWS v1.0.0 to production environments with enterprise-grade reliability, security, and scalability.

### Deployment Options Supported

| Option | Complexity | Cost | Best For |
|--------|-----------|------|----------|
| **Docker Compose** | Low | $ | Single server, small teams |
| **Kubernetes** | High | $$ | Multi-region, enterprise |
| **AWS ECS/Fargate** | Medium | $$ | AWS-native, auto-scaling |
| **AWS Elastic Beanstalk** | Low | $ | Quick AWS deployment |
| **Heroku** | Very Low | $$$ | Demos, prototypes |

---

## Prerequisites

### Required Tools

```bash
# Install required CLI tools
# Terraform (v1.5+)
brew install terraform  # macOS
# or
wget https://releases.hashicorp.com/terraform/1.5.0/terraform_1.5.0_linux_amd64.zip

# AWS CLI (v2+)
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

# kubectl (for Kubernetes)
curl -LO "https://dl.k8s/release/$(curl -L -s https://dl.k8s/release/stable.txt)/bin/linux/amd64/kubectl"

# Docker & Docker Compose
docker --version  # >= 20.10
docker-compose --version  # >= 2.0
```

### AWS Account Setup

```bash
# Configure AWS credentials
aws configure
# AWS Access Key ID: YOUR_ACCESS_KEY
# AWS Secret Access Key: YOUR_SECRET_KEY
# Default region name: us-east-1
# Default output format: json

# Verify access
aws sts get-caller-identity
```

### Domain & SSL

1. Register domain (Route53 recommended)
2. Request SSL certificate in AWS Certificate Manager (ACM)
3. Note the certificate ARN for Terraform

---

## Deployment Options

### Option 1: Docker Compose (Single Server)

**Best for:** Small deployments, homelab, < 100 concurrent users

#### Server Requirements

- **OS:** Ubuntu 22.04 LTS / Amazon Linux 2023
- **CPU:** 2+ cores
- **RAM:** 4GB+ (8GB recommended)
- **Storage:** 50GB+ SSD
- **Network:** Public IP, ports 80/443 open

#### Quick Deploy

```bash
# 1. Clone repository
git clone https://github.com/yourorg/mockupAWS.git
cd mockupAWS

# 2. Copy production configuration
cp .env.production.example .env.production

# 3. Edit environment variables
nano .env.production

# 4. Run production deployment script
chmod +x scripts/deployment/deploy-docker-compose.sh
./scripts/deployment/deploy-docker-compose.sh production

# 5. Verify deployment
curl -f http://localhost:8000/api/v1/health || echo "Health check failed"
```

#### Manual Setup

```bash
# 1. Install Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

# 2. Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# 3. Create production environment file
cat > .env.production << 'EOF'
# Application
APP_NAME=mockupAWS
APP_ENV=production
DEBUG=false
API_V1_STR=/api/v1

# Database (use strong password)
DATABASE_URL=postgresql+asyncpg://mockupaws:STRONG_PASSWORD@postgres:5432/mockupaws
POSTGRES_USER=mockupaws
POSTGRES_PASSWORD=STRONG_PASSWORD
POSTGRES_DB=mockupaws

# JWT (generate with: openssl rand -hex 32)
JWT_SECRET_KEY=GENERATE_32_CHAR_SECRET
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7
BCRYPT_ROUNDS=12
API_KEY_PREFIX=mk_

# Redis (for caching & Celery)
REDIS_URL=redis://redis:6379/0
CACHE_TTL=300

# Email (SendGrid recommended)
EMAIL_PROVIDER=sendgrid
SENDGRID_API_KEY=sg_your_key_here
EMAIL_FROM=noreply@yourdomain.com

# Frontend
FRONTEND_URL=https://yourdomain.com
ALLOWED_HOSTS=yourdomain.com,api.yourdomain.com

# Storage
REPORTS_STORAGE_PATH=/app/storage/reports
REPORTS_MAX_FILE_SIZE_MB=50
REPORTS_CLEANUP_DAYS=30

# Scheduler
SCHEDULER_ENABLED=true
SCHEDULER_INTERVAL_MINUTES=5
EOF

# 4. Create docker-compose.production.yml
cat > docker-compose.production.yml << 'EOF'
version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    container_name: mockupaws-postgres
    restart: always
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./backups:/backups
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - mockupaws

  redis:
    image: redis:7-alpine
    container_name: mockupaws-redis
    restart: always
    command: redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 5
    networks:
      - mockupaws

  backend:
    image: mockupaws/backend:v1.0.0
    container_name: mockupaws-backend
    restart: always
    env_file:
      - .env.production
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    volumes:
      - reports_storage:/app/storage/reports
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/api/v1/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    networks:
      - mockupaws

  frontend:
    image: mockupaws/frontend:v1.0.0
    container_name: mockupaws-frontend
    restart: always
    environment:
      - VITE_API_URL=/api/v1
    depends_on:
      - backend
    networks:
      - mockupaws

  nginx:
    image: nginx:alpine
    container_name: mockupaws-nginx
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./nginx/ssl:/etc/nginx/ssl:ro
      - reports_storage:/var/www/reports:ro
    depends_on:
      - backend
      - frontend
    networks:
      - mockupaws

  scheduler:
    image: mockupaws/backend:v1.0.0
    container_name: mockupaws-scheduler
    restart: always
    command: python -m src.jobs.scheduler
    env_file:
      - .env.production
    depends_on:
      - postgres
      - redis
    networks:
      - mockupaws

volumes:
  postgres_data:
  redis_data:
  reports_storage:

networks:
  mockupaws:
    driver: bridge
EOF

# 5. Deploy
docker-compose -f docker-compose.production.yml up -d

# 6. Run migrations
docker-compose -f docker-compose.production.yml exec backend \
  alembic upgrade head
```

---

### Option 2: Kubernetes

**Best for:** Enterprise, multi-region, auto-scaling, > 1000 users

#### Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                         INGRESS                              │
│              (nginx-ingress / AWS ALB)                       │
└──────────────────┬──────────────────────────────────────────┘
                   │
    ┌──────────────┼──────────────┐
    ▼              ▼              ▼
┌────────┐   ┌──────────┐   ┌──────────┐
│ Frontend│   │  Backend  │   │  Backend  │
│  Pods   │   │  Pods     │   │  Pods     │
│  (3)    │   │  (3+)     │   │  (3+)     │
└────────┘   └──────────┘   └──────────┘
                   │
    ┌──────────────┼──────────────┐
    ▼              ▼              ▼
┌────────┐   ┌──────────┐   ┌──────────┐
│PostgreSQL│  │  Redis   │   │  Celery   │
│Primary │   │ Cluster  │   │ Workers   │
└────────┘   └──────────┘   └──────────┘
```

#### Deploy with kubectl

```bash
# 1. Create namespace
kubectl create namespace mockupaws

# 2. Apply configurations
kubectl apply -f infrastructure/k8s/namespace.yaml
kubectl apply -f infrastructure/k8s/configmap.yaml
kubectl apply -f infrastructure/k8s/secrets.yaml
kubectl apply -f infrastructure/k8s/postgres.yaml
kubectl apply -f infrastructure/k8s/redis.yaml
kubectl apply -f infrastructure/k8s/backend.yaml
kubectl apply -f infrastructure/k8s/frontend.yaml
kubectl apply -f infrastructure/k8s/ingress.yaml

# 3. Verify deployment
kubectl get pods -n mockupaws
kubectl get svc -n mockupaws
kubectl get ingress -n mockupaws
```

#### Helm Chart (Recommended)

```bash
# Install Helm chart
helm upgrade --install mockupaws ./helm/mockupaws \
  --namespace mockupaws \
  --create-namespace \
  --values values-production.yaml \
  --set image.tag=v1.0.0

# Verify
helm list -n mockupaws
kubectl get pods -n mockupaws
```

---

### Option 3: AWS ECS/Fargate

**Best for:** AWS-native, serverless containers, auto-scaling

#### Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     Route53 (DNS)                            │
└──────────────────┬──────────────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────────────┐
│                 CloudFront (CDN)                             │
└──────────────────┬──────────────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────────────┐
│              Application Load Balancer                       │
│              (SSL termination)                               │
└────────────┬─────────────────────┬───────────────────────────┘
             │                     │
    ┌────────▼────────┐   ┌────────▼────────┐
    │   ECS Service   │   │   ECS Service   │
    │   (Backend)     │   │   (Frontend)    │
    │   Fargate       │   │   Fargate       │
    └────────┬────────┘   └─────────────────┘
             │
    ┌────────▼────────────────┬───────────────┐
    │                         │               │
┌───▼────┐              ┌────▼────┐   ┌──────▼──────┐
│  RDS   │              │ElastiCache│   │    S3       │
│PostgreSQL│             │  Redis   │   │  Reports    │
│Multi-AZ │              │ Cluster  │   │  Backups    │
└────────┘              └─────────┘   └─────────────┘
```

#### Deploy with Terraform

```bash
# 1. Initialize Terraform
cd infrastructure/terraform/environments/prod
terraform init

# 2. Plan deployment
terraform plan -var="environment=production" -out=tfplan

# 3. Apply deployment
terraform apply tfplan

# 4. Get outputs
terraform output
```

#### Manual ECS Setup

```bash
# 1. Create ECS cluster
aws ecs create-cluster --cluster-name mockupaws-production

# 2. Register task definitions
aws ecs register-task-definition --cli-input-json file://task-backend.json
aws ecs register-task-definition --cli-input-json file://task-frontend.json

# 3. Create services
aws ecs create-service \
  --cluster mockupaws-production \
  --service-name backend \
  --task-definition mockupaws-backend:1 \
  --desired-count 2 \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[subnet-xxx],securityGroups=[sg-xxx],assignPublicIp=ENABLED}"

# 4. Deploy new version
aws ecs update-service \
  --cluster mockupaws-production \
  --service backend \
  --task-definition mockupaws-backend:2
```

---

### Option 4: AWS Elastic Beanstalk

**Best for:** Quick AWS deployment with minimal configuration

```bash
# 1. Install EB CLI
pip install awsebcli

# 2. Initialize application
cd mockupAWS
eb init -p docker mockupaws

# 3. Create environment
eb create mockupaws-production \
  --single \
  --envvars "APP_ENV=production,JWT_SECRET_KEY=xxx"

# 4. Deploy
eb deploy

# 5. Open application
eb open
```

---

### Option 5: Heroku

**Best for:** Demos, prototypes, quick testing

```bash
# 1. Install Heroku CLI
brew install heroku

# 2. Login
heroku login

# 3. Create app
heroku create mockupaws-demo

# 4. Add addons
heroku addons:create heroku-postgresql:mini
heroku addons:create heroku-redis:mini

# 5. Set config vars
heroku config:set APP_ENV=production
heroku config:set JWT_SECRET_KEY=$(openssl rand -hex 32)
heroku config:set FRONTEND_URL=https://mockupaws-demo.herokuapp.com

# 6. Deploy
git push heroku main

# 7. Run migrations
heroku run alembic upgrade head
```

---

## Infrastructure as Code

### Terraform Structure

```
infrastructure/terraform/
├── modules/
│   ├── vpc/           # Network infrastructure
│   ├── rds/           # PostgreSQL database
│   ├── elasticache/   # Redis cluster
│   ├── ecs/           # Container orchestration
│   ├── alb/           # Load balancer
│   ├── cloudfront/    # CDN
│   ├── s3/            # Storage & backups
│   └── security/      # WAF, Security Groups
└── environments/
    ├── dev/
    ├── staging/
    └── prod/
        ├── main.tf
        ├── variables.tf
        ├── outputs.tf
        └── terraform.tfvars
```

### Deploy Production Infrastructure

```bash
# 1. Navigate to production environment
cd infrastructure/terraform/environments/prod

# 2. Create terraform.tfvars
cat > terraform.tfvars << 'EOF'
environment = "production"
region = "us-east-1"

# VPC Configuration
vpc_cidr = "10.0.0.0/16"
availability_zones = ["us-east-1a", "us-east-1b", "us-east-1c"]

# Database
db_instance_class = "db.r6g.xlarge"
db_multi_az = true

# ECS
ecs_task_cpu = 1024
ecs_task_memory = 2048
ecs_desired_count = 3
ecs_max_count = 10

# Domain
domain_name = "mockupaws.com"
certificate_arn = "arn:aws:acm:us-east-1:123456789012:certificate/xxx"

# Alerts
alert_email = "ops@mockupaws.com"
EOF

# 3. Deploy
terraform init
terraform plan
terraform apply

# 4. Save state (important!)
# Terraform state is stored in S3 backend (configured in backend.tf)
```

---

## CI/CD Pipeline

### GitHub Actions Workflow

The CI/CD pipeline includes:
- **Build:** Docker images for frontend and backend
- **Test:** Unit tests, integration tests, E2E tests
- **Security:** Vulnerability scanning (Trivy, Snyk)
- **Deploy:** Blue-green deployment to production

#### Workflow Diagram

```
┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
│  Push   │──>│  Build  │──>│  Test   │──>│  Scan   │──>│ Deploy  │
│  main   │   │ Images  │   │  Suite  │   │ Security│   │Staging  │
└─────────┘   └─────────┘   └─────────┘   └─────────┘   └─────────┘
                                                              │
                                                              ▼
┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
│  Done   │──>│ Monitor │──>│ Promote │──>│  E2E    │──>│ Manual  │
│         │   │ 1 hour  │   │to Prod  │   │  Tests  │   │ Approval│
└─────────┘   └─────────┘   └─────────┘   └─────────┘   └─────────┘
```

#### Pipeline Configuration

See `.github/workflows/deploy-production.yml` for the complete workflow.

#### Manual Deployment

```bash
# Trigger production deployment via GitHub CLI
gh workflow run deploy-production.yml \
  --ref main \
  -f environment=production \
  -f version=v1.0.0
```

---

## Environment Configuration

### Environment Variables by Environment

| Variable | Development | Staging | Production |
|----------|-------------|---------|------------|
| `APP_ENV` | `development` | `staging` | `production` |
| `DEBUG` | `true` | `false` | `false` |
| `LOG_LEVEL` | `DEBUG` | `INFO` | `WARN` |
| `RATE_LIMIT` | 1000/min | 500/min | 100/min |
| `CACHE_TTL` | 60s | 300s | 600s |
| `DB_POOL_SIZE` | 10 | 20 | 50 |

### Secrets Management

#### AWS Secrets Manager (Production)

```bash
# Store secrets
aws secretsmanager create-secret \
  --name mockupaws/production/database \
  --secret-string '{"username":"mockupaws","password":"STRONG_PASSWORD"}'

# Retrieve in application
aws secretsmanager get-secret-value \
  --secret-id mockupaws/production/database
```

#### HashiCorp Vault (Alternative)

```bash
# Store secrets
vault kv put secret/mockupaws/production \
  database_url="postgresql://..." \
  jwt_secret="xxx"

# Retrieve
vault kv get secret/mockupaws/production
```

---

## Security Considerations

### Production Security Checklist

- [ ] All secrets stored in AWS Secrets Manager / Vault
- [ ] Database encryption at rest enabled
- [ ] SSL/TLS certificates valid and auto-renewing
- [ ] Security groups restrict access to necessary ports only
- [ ] WAF rules configured (SQL injection, XSS protection)
- [ ] DDoS protection enabled (AWS Shield)
- [ ] Regular security audits scheduled
- [ ] Penetration testing completed

### Network Security

```yaml
# Security Group Rules
Inbound:
  - Port 443 (HTTPS) from 0.0.0.0/0
  - Port 80 (HTTP) from 0.0.0.0/0  # Redirects to HTTPS
  
Internal:
  - Port 5432 (PostgreSQL) from ECS tasks only
  - Port 6379 (Redis) from ECS tasks only
  
Outbound:
  - All traffic allowed (for AWS API access)
```

---

## Troubleshooting

### Common Issues

#### Database Connection Failed

```bash
# Check RDS security group
aws ec2 describe-security-groups --group-ids sg-xxx

# Test connection from ECS task
aws ecs execute-command \
  --cluster mockupaws \
  --task task-id \
  --container backend \
  --interactive \
  --command "pg_isready -h rds-endpoint"
```

#### High Memory Usage

```bash
# Check container metrics
aws cloudwatch get-metric-statistics \
  --namespace AWS/ECS \
  --metric-name MemoryUtilization \
  --dimensions Name=ClusterName,Value=mockupaws \
  --start-time 2026-04-07T00:00:00Z \
  --end-time 2026-04-07T23:59:59Z \
  --period 3600 \
  --statistics Average
```

#### SSL Certificate Issues

```bash
# Verify certificate
openssl s_client -connect yourdomain.com:443 -servername yourdomain.com

# Check certificate expiration
echo | openssl s_client -servername yourdomain.com -connect yourdomain.com:443 2>/dev/null | openssl x509 -noout -dates
```

---

## Rollback Procedures

### Quick Rollback (ECS)

```bash
# Rollback to previous task definition
aws ecs update-service \
  --cluster mockupaws-production \
  --service backend \
  --task-definition mockupaws-backend:PREVIOUS_REVISION \
  --force-new-deployment

# Monitor rollback
aws ecs wait services-stable \
  --cluster mockupaws-production \
  --services backend
```

### Database Rollback

```bash
# Restore from snapshot
aws rds restore-db-instance-from-db-snapshot \
  --db-instance-identifier mockupaws-restored \
  --db-snapshot-identifier mockupaws-snapshot-2026-04-07

# Update application to use restored database
aws ecs update-service \
  --cluster mockupaws-production \
  --service backend \
  --force-new-deployment
```

### Emergency Rollback Script

```bash
#!/bin/bash
# scripts/deployment/rollback.sh

ENVIRONMENT=$1
REVISION=$2

echo "Rolling back $ENVIRONMENT to revision $REVISION..."

# Update ECS service
aws ecs update-service \
  --cluster mockupaws-$ENVIRONMENT \
  --service backend \
  --task-definition mockupaws-backend:$REVISION \
  --force-new-deployment

# Wait for stabilization
aws ecs wait services-stable \
  --cluster mockupaws-$ENVIRONMENT \
  --services backend

echo "Rollback complete!"
```

---

## Support

For deployment support:
- **Documentation:** https://docs.mockupaws.com
- **Issues:** https://github.com/yourorg/mockupAWS/issues
- **Email:** devops@mockupaws.com
- **Emergency:** +1-555-DEVOPS (24/7 on-call)

---

## Appendix

### A. Cost Estimation

| Component | Monthly Cost (USD) |
|-----------|-------------------|
| ECS Fargate (3 tasks) | $150-300 |
| RDS PostgreSQL (Multi-AZ) | $200-400 |
| ElastiCache Redis | $50-100 |
| ALB | $20-50 |
| CloudFront | $20-50 |
| S3 Storage | $10-30 |
| Route53 | $5-10 |
| **Total** | **$455-940** |

### B. Scaling Guidelines

| Users | ECS Tasks | RDS Instance | ElastiCache |
|-------|-----------|--------------|-------------|
| < 100 | 2 | db.t3.micro | cache.t3.micro |
| 100-500 | 3 | db.r6g.large | cache.r6g.large |
| 500-2000 | 5-10 | db.r6g.xlarge | cache.r6g.xlarge |
| 2000+ | 10+ | db.r6g.2xlarge | cache.r6g.xlarge |

---

*Document Version: 1.0.0*  
*Last Updated: 2026-04-07*