AWS ECS Deployment Architecture Guide

This guide provides a comprehensive overview of how MangoApps is deployed using Amazon Elastic Container Service (ECS) and the architecture components involved.

Overview

MangoApps uses AWS ECS (Elastic Container Service) to deploy and manage containerized applications in production. This architecture provides scalability, reliability, and efficient resource management.

Architecture Diagram

AWS ECS Architecture
└── ECS Cluster: MangoApps-Production-Cluster
    └── ECS Service: MangoApps-Production
        ├── Task Definition: ma-mangoops-production:3 (Blueprint for containers)
        ├── Current Configuration
        │   ├── Desired Count: 1
        │   ├── Running Count: 1
        │   └── Pending Count: 0
        └── ECS Task Instance
            ├── Container 1: ma-mangoops-production
            │   ├── Web Application (Rails 8.1 + Puma)
            │   ├── CPU: 1024 units
            │   ├── Memory: 2048 MB
            │   ├── Port: 4000
            │   └── Essential: true
            └── Container 2: ma-mangoops-production-worker
                ├── Background Worker (GoodJob Processor)
                ├── Background Jobs Processing
                └── Essential: true

Supporting Services:
├── ECR Repository: Container Images
├── CloudWatch Logs: Application Logging
├── PostgreSQL Database: Production Database
├── Load Balancer: Traffic Distribution
├── S3 Storage: File Storage
├── SendGrid: Email Service
└── OpenAI: AI Services

Core Components

1. ECS Cluster

• Name: MangoApps-Production-Cluster
• Purpose: Logical grouping of compute resources
• Type: EC2 launch type for cost optimization
• Status: Active with 1 service running

2. ECS Service

• Name: MangoApps-Production
• Purpose: Manages desired number of tasks and handles deployments
• Desired Count: 1 task instance
• Deployment Strategy: Rolling updates with zero downtime
• Health Checks: Automatic task replacement on failure

3. Task Definition

• Name: ma-mangoops-production
• Revision: 3 (current active version)
• Purpose: Blueprint defining containers, resources, and configuration
• Launch Type: EC2
• Network Mode: Bridge

4. Containers per Task

Main Web Container (ma-mangoops-production)

• Image: 760042596542.dkr.ecr.us-east-1.amazonaws.com/ma-mangoops-production:production-305
• CPU: 1024 units (1 vCPU equivalent)
• Memory: 2048 MB reserved
• Port Mapping: 4000:4000
• Essential: Yes (task fails if this container stops)
• Purpose: Serves the Rails application with Puma web server

Background Worker Container (ma-mangoops-production-worker)

• Purpose: Processes background jobs using GoodJob
• Essential: Yes
• Shared Resources: Uses same task definition resources
• Function: Handles asynchronous tasks, email processing, data processing

Supporting Infrastructure

Container Registry (ECR)

• Repository: 760042596542.dkr.ecr.us-east-1.amazonaws.com/ma-mangoops-production
• Purpose: Stores Docker images for deployment
• Recent Images:
  • production-305 (current)
  • production-304
  • production-301

CloudWatch Logs

• Main Application Logs: /ecs/ma-mangoops-production
• Worker Logs: /ecs/ma-mangoops-production-worker
• Retention: 30 days
• Purpose: Centralized logging for monitoring and debugging

Database

• Type: PostgreSQL 17 with pgvector extension
• Connection: Via environment variables
• Features: Vector similarity search, JSONB operations, full-text search

External Dependencies

• Load Balancer: Distributes traffic to ECS tasks
• S3 Storage: File uploads and static assets
• SendGrid: Email delivery service
• OpenAI: AI assistant functionality

Deployment Process

1. Image Build

# Docker image is built from Dockerfile
docker build -t ma-mangoops-production .

2. Image Push to ECR

# Tagged and pushed to ECR repository
docker tag ma-mangoops-production:latest 760042596542.dkr.ecr.us-east-1.amazonaws.com/ma-mangoops-production:production-305
docker push 760042596542.dkr.ecr.us-east-1.amazonaws.com/ma-mangoops-production:production-305

3. Task Definition Update

• New task definition revision created with updated image
• Environment variables and resource allocation configured
• Container definitions updated

4. Service Update

• ECS service updated to use new task definition
• Rolling deployment ensures zero downtime
• Health checks validate new tasks before replacing old ones

Monitoring and Health Checks

Service Health

• Running Tasks: Monitored continuously
• Service Events: Logged for troubleshooting
• Auto Recovery: Failed tasks automatically replaced

Application Health

• Rails Application: Responds on port 4000
• Background Jobs: GoodJob processes queued tasks
• Database Connection: Monitored via application logs

Log Monitoring

# Check service status
aws ecs describe-services --cluster MangoApps-Production-Cluster --services MangoApps-Production

# View recent logs
aws logs get-log-events --log-group-name "/ecs/ma-mangoops-production" --log-stream-name "ecs/ma-mangoops-production/[TASK-ID]"

Scaling Configuration

Current Setup

• Desired Count: 1 task
• Min Capacity: 1 task
• Max Capacity: Can be increased as needed

Scaling Considerations

• Vertical Scaling: Increase CPU/memory in task definition
• Horizontal Scaling: Increase desired count for more task instances
• Auto Scaling: Can be configured based on CPU/memory utilization

Security

Network Security

• VPC: Deployed within private subnets
• Security Groups: Restrict access to necessary ports only
• Load Balancer: SSL termination and traffic filtering

Container Security

• Image Scanning: ECR scans for vulnerabilities
• IAM Roles: Task execution roles with minimal permissions
• Environment Variables: Sensitive data via AWS Secrets Manager

Troubleshooting

Common Issues

Task Restart Loops

• Symptom: Tasks continuously restart every few minutes
• Causes: Application crashes, health check failures, resource constraints
• Solution: Check CloudWatch logs for error messages

Failed Deployments

• Symptom: New task definition doesn’t deploy successfully
• Causes: Image pull errors, configuration issues, resource limits
• Solution: Verify ECR image exists and task definition is valid

Resource Exhaustion

• Symptom: Tasks fail to start or get killed
• Causes: Insufficient CPU/memory allocation
• Solution: Increase resource allocation in task definition

Diagnostic Commands

# Check ECS infrastructure status
./scripts/check-ecs-status.sh

# View service events
aws ecs describe-services --cluster MangoApps-Production-Cluster --services MangoApps-Production

# List running tasks
aws ecs list-tasks --cluster MangoApps-Production-Cluster --service-name MangoApps-Production

# Check task definition
aws ecs describe-task-definition --task-definition ma-mangoops-production:3

Best Practices

Resource Management

• Right-sizing: Allocate appropriate CPU and memory based on usage patterns
• Reserved Capacity: Use EC2 reserved instances for cost optimization
• Monitoring: Set up CloudWatch alarms for resource utilization

Deployment Strategy

• Blue-Green Deployments: For zero-downtime deployments
• Health Checks: Implement proper application health endpoints
• Rollback Plan: Keep previous task definition versions for quick rollback

Monitoring

• Centralized Logging: Use CloudWatch for all application logs
• Metrics: Monitor key performance indicators
• Alerting: Set up notifications for critical issues

Environment Variables

Key environment variables configured in the task definition:

RAILS_ENV=production
POSTGRES_PROD_HOST=[database-endpoint]
POSTGRES_PROD_USER=[database-user]
POSTGRES_PROD_PASSWORD=[database-password]
RAILS_MASTER_KEY=[rails-master-key]
SECRET_KEY_BASE=[secret-key]
GOOD_JOB_IN_PUMA=true
AWS_ACCESS_KEY_ID=[aws-access-key]
AWS_SECRET_ACCESS_KEY=[aws-secret-key]
S3_STORAGE_KEY=[s3-access-key]
S3_STORAGE_SECRET=[s3-secret-key]
BASE_URL=https://workforce.mangoapps.com

Conclusion

This ECS deployment architecture provides a robust, scalable foundation for MangoApps production environment. The containerized approach ensures consistency across environments while ECS handles orchestration, scaling, and health management automatically.

For additional support or questions about the deployment architecture, contact the development team or refer to the AWS ECS documentation.

---

Internal Use Only: This article contains sensitive infrastructure information and should only be accessible to super administrators and development team members.