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
2. Prerequisites
3. Deployment Options
4. Infrastructure as Code
5. CI/CD Pipeline
6. Environment Configuration
7. Security Considerations
8. Troubleshooting
9. 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

# 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

# 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

# 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

# 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

# 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)

# 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

# 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

# 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

# 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

# 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

# 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

# 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)

# 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)

# 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

# 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

# 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

# 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

# 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)

# 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

# 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

#!/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