docs(ecs): Update README with latest instructions

Author: CuriousLearner

template/deploy/{% if 'aws-ecs-fargate' in deployment_targets %}ecs{% endif %}/README.md.jinja

@@ -10,14 +10,16 @@ This directory contains a complete implementation for deploying to AWS ECS Farga
 
 - **Complete Terraform Configuration**: Full IaC setup with modular architecture
 - **Automated Deployment Script**: One-command deployment with `deploy.sh`
-- **CI/CD Pipeline**: GitHub Actions workflow for automated deployments
+- **CI/CD Pipeline**: GitHub Actions workflow with automatic rollback
 - **Networking**: VPC with public/private subnets, NAT gateways, and VPC endpoints
 - **Database Options**: RDS PostgreSQL or Aurora Serverless v2
-- **Storage**: S3 buckets for static/media files with CDN-ready configuration
-- **Security**: Secrets Manager, IAM roles, security groups
-- **Monitoring**: CloudWatch logs, metrics, and alarms
-- **Auto-scaling**: Target tracking and scheduled scaling
-- **Cost Optimization**: Fargate Spot support, right-sizing recommendations
+- **Storage**: S3 buckets for static/media files with encryption
+- **Security**: Secrets Manager, IAM roles, security groups, SSL/TLS certificates
+- **Monitoring**: CloudWatch logs, alarms, SNS notifications, and dashboard
+- **Auto-scaling**: Multi-metric target tracking (CPU, Memory, Requests)
+- **DNS Management**: Route53 hosted zone and automatic certificate validation
+- **Migration Management**: Terraform-managed database migration tasks
+- **Cost Optimization**: Fargate Spot support, single NAT for non-prod, lifecycle policies
 
 ### 📁 Directory Structure
 
@@ -29,12 +31,13 @@ ecs/
 │   ├── variables.tf             # Input variables
 │   ├── outputs.tf               # Output values
 │   ├── network.tf               # VPC and networking
-│   ├── ecs.tf                   # ECS cluster and services
+│   ├── ecs.tf                   # ECS cluster, services, and auto-scaling
 │   ├── alb.tf                   # Application Load Balancer
 │   ├── database.tf              # RDS/Aurora configuration
 │   ├── storage.tf               # S3 and Redis
-│   ├── security.tf              # Security groups and secrets
+│   ├── security.tf              # Security groups, secrets, and Route53
 │   ├── ecr.tf                   # Container registry
+│   ├── monitoring.tf            # CloudWatch alarms and dashboard
 │   └── terraform.tfvars.example # Example variables file
 └── .github-workflows-ecs.yml   # GitHub Actions CI/CD
 ```
@@ -47,6 +50,23 @@ ecs/
 - jq for JSON processing
 - Python {{ python_version }} with Django installed
 
+## HTTPS and Custom Domain
+
+**Important:** HTTPS is only available when using a custom domain. The deployment supports two modes:
+
+1. **HTTP-only (Development/Testing)**
+   - Set `domain_name = ""` in terraform.tfvars
+   - Access via ALB DNS name (e.g., `http://myapp-alb-123456.us-east-1.elb.amazonaws.com`)
+   - No SSL/TLS certificate required
+
+2. **HTTPS with Custom Domain (Production)**
+   - Set `domain_name = "example.com"` and `create_dns_zone = true` in terraform.tfvars
+   - Terraform creates Route53 hosted zone and ACM certificate
+   - HTTP traffic automatically redirects to HTTPS
+   - Update your domain's nameservers to point to Route53
+
+**Note:** AWS ALB DNS names cannot be used with ACM certificates. For production deployments with HTTPS, a custom domain is required.
+
 ## Quick Start
 
 ### Option 1: Automated Deployment (Recommended)
@@ -232,15 +252,18 @@ The ECS task definition includes:
 
 ### Auto Scaling
 
-Auto-scaling configuration:
+Comprehensive auto-scaling with multiple metrics:
 
-- **Min Tasks**: 2
-- **Max Tasks**: 10
-- **Target CPU**: 70%
-- **Target Memory**: 80%
+- **Min Tasks**: 2 (production), 1 (dev/staging)
+- **Max Tasks**: 10 (production), 3 (dev/staging)
+- **CPU-based scaling**: Target 70% utilization
+- **Memory-based scaling**: Target 80% utilization
+- **Request-based scaling**: Target 1000 requests per target
 - **Scale-in Cooldown**: 300s
 - **Scale-out Cooldown**: 60s
 
+The service uses target tracking policies for all three metrics and will scale based on whichever metric needs the most capacity. This ensures responsive scaling under various load patterns.
+
 ## Database Options
 
 ### RDS PostgreSQL
@@ -279,102 +302,227 @@ STATICFILES_STORAGE = "storages.backends.s3boto3.S3StaticStorage"
 DEFAULT_FILE_STORAGE = "storages.backends.s3boto3.S3Boto3Storage"
 ```
 
+## DNS and Domain Configuration
+
+### Route53 Setup (Optional)
+
+If using a custom domain, Terraform can manage your DNS:
+
+**1. Configure domain in terraform.tfvars:**
+```hcl
+domain_name      = "example.com"
+create_dns_zone  = true
+```
+
+**2. Terraform creates:**
+- Route53 hosted zone for your domain
+- ACM certificate with automatic DNS validation
+- A records pointing to your ALB (apex and www)
+- Certificate validation records
+
+**3. Update your domain registrar:**
+```bash
+# Get nameservers from Terraform output
+terraform output domain_nameservers
+
+# Update your domain registrar (e.g., Namecheap, GoDaddy) with these nameservers:
+# ns-123.awsdns-12.com
+# ns-456.awsdns-45.net
+# ns-789.awsdns-78.org
+# ns-012.awsdns-01.co.uk
+```
+
+**4. Certificate validation:**
+- Automatic when using Route53 (Terraform creates validation records)
+- Manual if using external DNS (add CNAME records from ACM console)
+
+**5. Access your application:**
+- `https://example.com` - Apex domain
+- `https://www.example.com` - WWW subdomain
+- Both automatically redirect HTTP → HTTPS
+
+### Using Existing DNS Provider
+
+If you manage DNS externally:
+
+```hcl
+domain_name      = "example.com"
+create_dns_zone  = false  # Don't create Route53 zone
+```
+
+Then manually create:
+- ACM certificate validation records (from AWS Console)
+- A record pointing to ALB DNS name (from `terraform output alb_dns_name`)
+
 ## Migrations
 
-### One-Time Migrations
+### Terraform-Managed Migration Task
+
+Database migrations are managed as a Terraform resource (`ecs_migrate` task definition). This ensures consistency with your application container and simplifies deployment.
 
-Run migrations as a one-off task:
+### Running Migrations
 
+**Using deploy.sh (Recommended):**
 ```bash
-aws ecs run-task \
-  --cluster {{ project_slug }}-cluster \
-  --task-definition {{ project_slug }}-migrate \
-  --launch-type FARGATE \
-  --network-configuration "awsvpcConfiguration={subnets=[subnet-xxx],securityGroups=[sg-xxx],assignPublicIp=ENABLED}"
+./deploy/ecs/deploy.sh
+# Then select option 5: "Run migrations"
 ```
 
-### Automated Migrations
+The script will:
+1. Get the migration task definition from Terraform
+2. Run the task in your private subnets
+3. Wait for completion and validate exit code
+4. Show migration logs
 
-Use ECS Exec or create a migration task that runs before deployment.
+**Manual Execution:**
+```bash
+# Get task definition ARN from Terraform
+cd deploy/ecs/terraform
+MIGRATE_TASK_DEF=$(terraform output -raw ecs_migrate_task_definition)
+
+# Get subnet and security group IDs
+SUBNET_IDS=$(aws ec2 describe-subnets \
+  --filters "Name=tag:Type,Values=Private" \
+  --query "Subnets[*].SubnetId" --output text | tr '\t' ',')
+SECURITY_GROUP=$(aws ec2 describe-security-groups \
+  --filters "Name=tag:Name,Values=*app-sg" \
+  --query "SecurityGroups[0].GroupId" --output text)
+
+# Run migration
+TASK_ARN=$(aws ecs run-task \
+  --cluster {{ project_slug }}-{environment}-cluster \
+  --task-definition "$MIGRATE_TASK_DEF" \
+  --launch-type FARGATE \
+  --network-configuration "awsvpcConfiguration={subnets=[$SUBNET_IDS],securityGroups=[$SECURITY_GROUP],assignPublicIp=DISABLED}" \
+  --query 'tasks[0].taskArn' --output text)
 
-## Monitoring
+# Wait for completion
+aws ecs wait tasks-stopped --cluster {{ project_slug }}-{environment}-cluster --tasks "$TASK_ARN"
 
-### CloudWatch Metrics
+# Check exit code
+aws ecs describe-tasks \
+  --cluster {{ project_slug }}-{environment}-cluster \
+  --tasks "$TASK_ARN" \
+  --query 'tasks[0].containers[0].exitCode'
+```
 
-Key metrics to monitor:
+**In CI/CD:**
+Migrations run automatically before deployment in the GitHub Actions workflow with:
+- Proper wait conditions (no hardcoded sleeps)
+- Exit code validation
+- Automatic rollback on failure
 
-- CPU Utilization
-- Memory Utilization
-- Request Count
-- Target Response Time
-- Unhealthy Host Count
+## Monitoring
 
 ### CloudWatch Alarms
 
-Set up alarms for:
+Comprehensive monitoring with automated alerting (enabled via `enable_monitoring = true`):
+
+**ECS Service Alarms:**
+- **High CPU**: > 80% for 2 periods (5 min each)
+- **High Memory**: > 85% for 2 periods
+- **Unhealthy Targets**: Any unhealthy targets for 2 periods (1 min each)
 
-- High CPU (> 80%)
-- High Memory (> 85%)
-- Failed Health Checks
-- 5xx Error Rate
+**ALB Alarms:**
+- **5XX Errors**: > 10 errors in 5 minutes
+- **Response Time**: > 2 seconds average for 5 minutes
+
+**Database Alarms (RDS):**
+- **High CPU**: > 80% for 10 minutes
+- **Low Storage**: < 5GB free space
+- **High Connections**: > 80 concurrent connections
+
+{% if cache == 'redis' -%}
+**Redis Alarms:**
+- **High CPU**: > 75% for 10 minutes
+- **High Memory**: > 80% for 10 minutes
+{% endif %}
+
+**Notifications:**
+- Email notifications via SNS (configure `alarm_email` in terraform.tfvars)
+- All alarms tagged with environment and project
+- Alarms automatically integrate with AWS CloudWatch dashboard
+
+### CloudWatch Dashboard
+
+A pre-configured dashboard is created with:
+- ECS CPU and Memory utilization graphs
+- ALB request count, errors, and response time
+- Database connection count and CPU usage
+- All metrics updated in real-time
+
+Access via: AWS Console → CloudWatch → Dashboards → `{{ project_slug }}-{environment}-dashboard`
 
 ### Logs
 
 View logs:
 
 ```bash
 # Stream logs
-aws logs tail /ecs/{{ project_slug }} --follow
+aws logs tail /ecs/{{ project_slug }}-{environment} --follow
 
 # Filter for errors
 aws logs filter-log-events \
-  --log-group-name /ecs/{{ project_slug }} \
+  --log-group-name /ecs/{{ project_slug }}-{environment} \
   --filter-pattern "ERROR"
+
+# View specific service logs
+aws logs tail /ecs/{{ project_slug }}-{environment} --follow --filter-pattern "app"
+aws logs tail /ecs/{{ project_slug }}-{environment} --follow --filter-pattern "migrate"
+{% if use_celery -%}
+aws logs tail /ecs/{{ project_slug }}-{environment} --follow --filter-pattern "celery"
+{% endif -%}
 ```
 
 ## CI/CD Integration
 
 ### GitHub Actions
 
-```yaml
-name: Deploy to ECS
-
-on:
-  push:
-    branches: [main]
-
-jobs:
-  deploy:
-    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: {% raw %}${{ secrets.AWS_ACCESS_KEY_ID }}{% endraw %}
-          aws-secret-access-key: {% raw %}${{ secrets.AWS_SECRET_ACCESS_KEY }}{% endraw %}
-          aws-region: us-east-1
-
-      - name: Login to Amazon ECR
-        id: login-ecr
-        uses: aws-actions/amazon-ecr-login@v1
-
-      - name: Build and push image
-        env:
-          ECR_REGISTRY: {% raw %}${{ steps.login-ecr.outputs.registry }}{% endraw %}
-          IMAGE_TAG: {% raw %}${{ github.sha }}{% endraw %}
-        run: |
-          docker build -t $ECR_REGISTRY/{{ project_slug }}:$IMAGE_TAG .
-          docker push $ECR_REGISTRY/{{ project_slug }}:$IMAGE_TAG
-
-      - name: Deploy to ECS
-        run: |
-          aws ecs update-service \
-            --cluster {{ project_slug }}-cluster \
-            --service {{ project_slug }}-service \
-            --force-new-deployment
+The included workflow (`.github-workflows-ecs.yml`) provides:
+
+**Features:**
+- ✅ Automated testing on pull requests
+- ✅ Build and push to ECR with image caching
+- ✅ Separate staging and production deployments
+- ✅ Database migrations with validation
+- ✅ Health check verification with retries
+- ✅ **Automatic rollback on failure** (production only)
+- ✅ RDS snapshot before production deployment
+- ✅ Blue/Green deployment with circuit breaker
+- ✅ Slack notifications (optional)
+- ✅ Sentry release tracking (optional)
+
+**Deployment Flow:**
+
+1. **Test** (PR only): Run pytest and linting
+2. **Build**: Build Docker image with caching
+3. **Push**: Tag and push to ECR (`:latest`, `:sha`, `:branch-name`)
+4. **Backup**: Create RDS snapshot (production only)
+5. **Migrate**: Run database migrations with exit code validation
+6. **Deploy**: Update ECS service with new task definition
+7. **Wait**: Use proper AWS wait conditions (no hardcoded sleeps)
+8. **Verify**: Health checks with retry logic
+9. **Rollback**: Automatic rollback on failure (production only)
+10. **Notify**: Send notifications (Slack, Sentry)
+
+**Configuration:**
+
+Add these secrets to your GitHub repository:
 ```
+AWS_ACCESS_KEY_ID
+AWS_SECRET_ACCESS_KEY
+STAGING_SUBNET_IDS       # Comma-separated subnet IDs
+STAGING_SECURITY_GROUP_ID
+PRODUCTION_SUBNET_IDS
+PRODUCTION_SECURITY_GROUP_ID
+SLACK_WEBHOOK            # Optional
+SENTRY_AUTH_TOKEN        # Optional
+```
+
+**Trigger:**
+- `main` branch → Deploy to staging
+- `production` branch → Deploy to production
+- Manual workflow dispatch → Choose environment
 
 ## Cost Optimization