📖 Understanding GitHub Actions

GitHub Actions is a CI/CD platform that automates your software workflows. When you push code to GitHub, Actions can:

• Build: Compile your application and create Docker images
• Test: Run automated tests
• Deploy: Push images to ECR and update ECS services

Manual deployments are error-prone and time-consuming. CI/CD ensures consistent, automated deployments every time you push code – no more “it works on my machine” issues.

🔄 How the GitHub Actions Workflow Works

The CI/CD pipeline automates the entire deployment process. Here’s how it works step by step:

1. Trigger: When you push code to the main branch, GitHub Actions automatically detects the change and starts the workflow.
2. Checkout Code: The workflow checks out your repository code to the GitHub Actions runner (a virtual machine).
3. Configure AWS Credentials: Uses the AWS credentials stored in GitHub Secrets to authenticate with your AWS account.
4. Login to ECR: Authenticates Docker with Amazon ECR so it can push images.
5. Build Docker Image: Builds your application into a Docker image using the Dockerfile in your repository.
6. Tag Image: Tags the image with the Git commit SHA (unique identifier) for version tracking.
7. Push to ECR: Uploads the Docker image to your ECR repository.
8. Download Task Definition: Retrieves the current ECS task definition from AWS.
9. Update Task Definition: Updates the task definition with the new image URI (points to the newly pushed image).
10. Deploy to ECS: Updates the ECS service with the new task definition, triggering a rolling deployment.
11. Wait for Stability: Waits for the new tasks to become healthy before completing.

Rolling Deployment Process:

• ECS starts new tasks with the updated image
• New tasks register with the target group and pass health checks
• ALB gradually shifts traffic from old tasks to new tasks
• Old tasks are stopped once new tasks are healthy
• This ensures zero-downtime deployments

For Frontend Repository: The workflow builds the Next.js application, pushes to frontend-repo in ECR, and updates frontend-service in ECS.

For Backend Repository: The workflow builds the Node.js/TypeScript backend, pushes to backend-repo in ECR, and updates backend-service in ECS.

📋 Workflow Execution Summary

When you push code to the Frontend Repository:

1. GitHub Actions triggers the workflow
2. Builds Next.js frontend application into Docker image
3. Tags image with commit SHA (e.g., frontend-repo:abc123)
4. Pushes image to frontend-repo in ECR
5. Downloads current frontend-task task definition
6. Updates task definition with new image URI
7. Deploys updated task definition to frontend-service
8. ECS performs rolling update (starts new tasks, shifts traffic, stops old tasks)
9. New frontend version is live on ALB

When you push code to the Backend Repository:

1. GitHub Actions triggers the workflow
2. Builds Node.js/TypeScript backend application into Docker image
3. Tags image with commit SHA (e.g., backend-repo:xyz789)
4. Pushes image to backend-repo in ECR
5. Downloads current backend-task task definition
6. Updates task definition with new image URI
7. Deploys updated task definition to backend-service
8. ECS performs rolling update (starts new tasks, shifts traffic, stops old tasks)
9. New backend version is live and accessible via /api/* routes

📖 Understanding VPC

A Virtual Private Cloud (VPC) is your own isolated network environment within AWS. Think of it as your private data center in the cloud where you have complete control over:

• IP Address Ranges: Define your own CIDR blocks (e.g., 10.0.0.0/16)
• Subnets: Divide your network into public (internet-facing) and private (internal) subnets
• Routing: Control how traffic flows between subnets and to the internet
• Security: Implement network-level security with security groups and network ACLs

VPC provides network isolation and security. Your ECS tasks, RDS database, and load balancer all run within this isolated network, protected from the public internet except through controlled entry points.

📖 What are Security Groups?

Security Groups act as virtual firewalls that control inbound and outbound traffic for your AWS resources. Key characteristics:

• Stateful: If you allow inbound traffic, the response is automatically allowed outbound
• Resource-Level: Attached to network interfaces (EC2, RDS, ALB, ECS tasks)
• Rule-Based: Define rules based on protocol, port, and source/destination
• Default Deny: All traffic is denied by default unless explicitly allowed

Security groups provide the first line of defense, ensuring only authorized traffic reaches your resources. You’ll create three security groups:

• ALB-SG: Allows HTTP/HTTPS from internet to load balancer
• ECS-SG: Allows traffic from ALB to ECS tasks (ports 80, 3001)
• RDS-SG: Allows PostgreSQL traffic from ECS tasks only

📖 Understanding IAM Roles

IAM (Identity and Access Management) Roles are AWS identities with permission policies that define what actions can be performed. For ECS, you’ll work with two types:

• Task Execution Role: Used by ECS infrastructure to pull Docker images from ECR, write logs to CloudWatch, and read secrets from Parameter Store. This is required – without it, ECS can’t pull your images.
• Task Role: Used by your application code running inside containers to access AWS services (S3, DynamoDB, etc.). This is optional but recommended if your app needs AWS API access.

Roles follow the principle of least privilege – each component only gets the permissions it needs. The execution role handles infrastructure tasks, while the task role handles application-level AWS API calls.

📖 Understanding ECR

Amazon Elastic Container Registry (ECR) is a fully managed Docker container registry that stores, manages, and deploys Docker container images. It’s integrated with ECS, so pushing images and having ECS pull them is seamless.

Think of ECR as a private Docker Hub for your AWS account. When you build your application, you push the image to ECR, and ECS pulls it automatically when starting tasks. This keeps your images secure and close to where they’re used.

📖 Understanding RDS

Amazon Relational Database Service (RDS) is a managed database service that makes it easy to set up, operate, and scale relational databases in the cloud. Instead of managing database servers yourself, RDS handles:

• Provisioning: Automated database setup
• Backups: Automated daily backups with point-in-time recovery
• Scaling: Easy vertical scaling (instance size) and read replicas
• Maintenance: Automated patching and updates
• Monitoring: CloudWatch integration for metrics

Your backend application needs a database to store data. RDS provides a managed PostgreSQL database that’s secure, scalable, and reliable – no need to worry about database server management.

📖 Understanding ECS Clusters

Amazon ECS Cluster is a logical grouping of tasks or services. Think of it as a container for your containerized applications. For AWS Fargate:

• No Infrastructure Management: AWS manages all servers, containers, and networking – you just define what to run
• Namespace: Groups your services and tasks together in one logical unit
• Serverless: No EC2 instances to manage – Fargate handles everything
• Scaling: Automatically handles scaling based on demand and service configuration
• Integration: Works seamlessly with ALB, CloudWatch, ECR, Parameter Store, and other AWS services
• Multi-Service Support: Can run multiple services (frontend, backend) in the same cluster

The cluster is where your ECS services run. It provides the platform for running your containerized applications. Without a cluster, you cannot run ECS services or tasks – think of it as the foundation.

Important concepts:

• Cluster: The container that holds your services
• Service: Maintains a desired number of running tasks (e.g., frontend-service, backend-service)
• Task: A running instance of a task definition (your containerized application)
• Task Definition: Blueprint that describes how to run your container (CPU, memory, image, environment variables)

📖 Understanding Application Load Balancer

Application Load Balancer (ALB) is a Layer 7 (application layer) load balancer that distributes incoming HTTP/HTTPS traffic across multiple targets (your ECS tasks) in multiple Availability Zones. Think of it as a smart traffic director.

What ALB does:

• Layer 7 Routing: Routes based on HTTP/HTTPS content (URL path, host header, HTTP headers) – not just IP addresses
• Path-Based Routing: Routes /api/* to backend service, / to frontend service
• Health Checks: Continuously monitors target health and routes only to healthy targets
• SSL Termination: Handles SSL/TLS certificates – decrypts HTTPS traffic
• High Availability: Automatically distributes across multiple Availability Zones
• Auto Scaling: Automatically scales to handle traffic increases
• Sticky Sessions: Can maintain session affinity (optional)

The ALB gives you a single entry point (one DNS name) for your entire application. It distributes requests across multiple ECS tasks for better performance, and if one task fails, traffic automatically routes to healthy tasks. This enables zero-downtime deployments and path-based routing (API calls to backend, web pages to frontend).

How ALB Works:

1. User requests come to ALB DNS name (e.g., ecs-alb-xxx.elb.amazonaws.com)
2. ALB examines the request path
3. If path starts with /api/*, routes to backend target group
4. If path is anything else, routes to frontend target group
5. ALB performs health checks on targets
6. Only healthy targets receive traffic

🎯 Understanding Target Groups

A Target Group is a collection of targets (ECS tasks) that receive traffic from the load balancer. Think of it as a group of servers that handle the same type of requests.

Key Points:

• Frontend Target Group: Contains frontend ECS tasks (port 80)
• Backend Target Group: Contains backend ECS tasks (port 3001)
• Health Checks: ALB continuously checks if targets are healthy
• Auto Registration: ECS tasks automatically register with target groups when services are created

📖 Understanding CloudWatch Logs

Amazon CloudWatch Logs is a service for monitoring, storing, and accessing log files from AWS resources and applications. Here’s what it offers:

• Centralized Logging: All container logs in one place
• Search & Filter: Easy log searching and filtering
• Retention Policies: Automatically delete old logs
• Integration: ECS automatically sends container logs

You need to see what’s happening in your containers. CloudWatch Logs provides visibility into application behavior, errors, and performance – essential for debugging.

📖 Understanding Task Definitions

ECS Task Definition is a blueprint for your application. It describes:

• Container Images: Which Docker images to use
• Resources: CPU and memory allocation
• Ports: Which ports to expose
• Environment Variables: Configuration values
• Secrets: Secure values from Parameter Store
• Logging: Where to send container logs
• IAM Roles: Permissions for the task

Task definitions tell ECS exactly how to run your containers. You create the definition once, and ECS uses it to launch tasks – think of it as a recipe that ECS follows every time.

📖 Understanding Parameter Store

AWS Systems Manager Parameter Store provides secure, hierarchical storage for configuration data and secrets. Here’s what it offers:

• Secure Storage: Encrypted storage for sensitive data
• Types: String (plain text) or SecureString (encrypted)
• Integration: ECS automatically injects values as environment variables
• Versioning: Track changes to parameters
• Access Control: IAM-based permissions

Store database credentials, API URLs, and other configuration securely here. ECS tasks can access these values without hardcoding secrets in your code – much safer than putting passwords in environment variables.

📖 Understanding ECS Services

ECS Service runs and maintains a specified number of instances of a task definition simultaneously. Here’s what services handle:

• Desired Count: Maintains specified number of running tasks
• Load Balancing: Integrates with ALB to distribute traffic
• Auto Scaling: Can scale based on demand
• Rolling Updates: Zero-downtime deployments
• Health Monitoring: Restarts unhealthy tasks

Services ensure your application is always running. If a task crashes, the service automatically starts a new one. Services handle deployments and scaling – you don’t have to babysit your containers.

1. Q1: What problem does this whole ECS setup solve?
   A: It gives you a repeatable, reliable way to run your app in the cloud. Instead of running code on one fragile server, you package your app in containers, run them on ECS, and put an ALB in front so users always hit a healthy instance.
2. Q2: What is a container in simple words?
   A: A container is like a small, portable box that holds your app and everything it needs to run (libraries, runtime). If it runs on your laptop, it will run the same way in AWS.
3. Q3: How is ECS different from just using EC2 directly?
   A: With EC2 you manage servers yourself (patching, scaling, scheduling). With ECS, you tell AWS “run these containers like this” and ECS handles placement, health checks, and restarts for you.
4. Q4: Why do we need an ALB in front of ECS?
   A: ECS tasks (containers) come and go. The ALB is the stable entry point that knows which tasks are healthy and where to send each request. It also supports path-based routing, HTTPS, and health checks.
5. Q5: Why do we use Fargate instead of EC2 launch type?
   A: Fargate is “serverless for containers”. You don’t manage EC2 instances; you only define CPU/memory per task. AWS manages the underlying servers, which reduces ops work.
6. Q6: What is the difference between an ECS Task Definition and an ECS Service?
   A: The task definition is the blueprint (what to run, image, CPU, env vars). The service is the “manager” that ensures a certain number of those tasks are running and connected to the load balancer.
7. Q7: Why do we keep the database (RDS) in private subnets?
   A: So it’s not exposed to the internet. Only ECS tasks inside the VPC can talk to it, which is a big security win.
8. Q8: Why do we split frontend and backend into separate services?
   A: They scale differently and have different behavior. Splitting them lets you scale, deploy, and debug each independently.
9. Q9: What is the role of ECR in this architecture?
   A: ECR is a private Docker image registry. It stores your built images so ECS can pull them whenever it needs to start new tasks.
10. Q10: Why do we use CI/CD instead of manual deployments?
    A: CI/CD turns deployment into a repeatable, automated process. Every push builds, tests, and deploys in the same way, reducing human error and speeding up releases.

11. Q11: Why do we have both public and private subnets?
    A: Public subnets host internet-facing resources (like the ALB). Private subnets host sensitive workloads (ECS tasks, RDS) that should not be directly reachable from the internet.
12. Q12: How do ECS tasks access the internet if they are in private subnets?
    A: They go out through a NAT Gateway. This lets tasks download packages or talk to external APIs without being directly reachable from the internet.
13. Q13: What are Security Groups in this setup?
    A: Security Groups are virtual firewalls. For example, the ALB SG allows traffic from the internet on HTTP/HTTPS, and the ECS SG only allows traffic from the ALB SG.
14. Q14: How do we ensure only ECS tasks can talk to the database?
    A: The RDS Security Group only allows connections from the ECS Security Group on the database port. No other source is allowed.
15. Q15: What happens if one ECS task crashes?
    A: The ECS service detects that the task is unhealthy and starts a new one. The ALB stops sending traffic to the unhealthy task automatically.
16. Q16: How do health checks protect users?
    A: The ALB pings a health check endpoint (like / or /api/health). Only tasks that respond correctly are considered healthy and receive user traffic.
17. Q17: What is the difference between task execution role and task role?
    A: The execution role is used by ECS to pull images and write logs. The task role is used by your app code to call AWS services (like S3, Parameter Store).
18. Q18: How do we keep secrets (like DB password) out of the code?
    A: We store them in Parameter Store as SecureString values and let ECS inject them into the task as environment variables or secrets. The code just reads env vars.
19. Q19: How does scaling work in this design?
    A: The ECS service can be configured to scale the number of running tasks up or down based on metrics (CPU, requests). The ALB automatically balances traffic across all tasks.
20. Q20: What is the main single point of failure to watch out for?
    A: Misconfigured health checks, database availability, and limits like connection pools. The infrastructure is multi-AZ and managed, but bad configuration can still cause downtime.

21. Q21: What does the GitHub Actions workflow actually do step by step?
    A: It checks out code, configures AWS credentials, logs in to ECR, builds a Docker image, pushes it to ECR, updates the task definition with the new image, and asks ECS to deploy it.
22. Q22: Why do we tag images with the Git SHA?
    A: The Git SHA is a unique identifier for each commit. Tagging images with it makes deployments traceable and makes rollbacks easier.
23. Q23: How does ECS know which image to run after a deployment?
    A: The task definition is updated with the new image URI (including tag). The ECS service always runs the latest revision of the task definition.
24. Q24: What is a “task definition revision”?
    A: Every time you change the task definition (for example, new image or env var), ECS creates a new numbered revision. Services usually point to the latest revision.
25. Q25: How do CloudWatch Logs fit into this?
    A: Each container sends its stdout/stderr logs to a log group (like /ecs/frontend). You can search, filter, and debug issues centrally in CloudWatch.
26. Q26: What should I look at first when the app is “not working”?
    A: Check ECS service events (for deployment errors), ALB target health, and CloudWatch logs for the relevant task. This usually tells you if it’s a code error, health check issue, or config problem.
27. Q27: How do I roll back to a previous version?
    A: You can either re-deploy an older image tag via CI/CD, or manually update the service to use an older task definition revision that points to the previous image.
28. Q28: Why do we separate environment variables and secrets?
    A: Regular env vars hold non-sensitive config (like URLs); secrets are sensitive values stored in a secure service (Parameter Store) and injected securely. This reduces risk if logs or screenshots leak.
29. Q29: How does this design support future growth?
    A: You can add more services (microservices), scale tasks independently, add caching layers, and extend CI/CD, all without redesigning the whole system. The building blocks are already in place.
30. Q30: How would you explain this architecture to a non‑technical stakeholder?
    A: We have a front door (ALB) that safely receives traffic, smart workers (ECS tasks) that handle requests, a secure vault (RDS + Parameter Store) for data and secrets, and an assembly line (CI/CD) that ships new versions automatically and safely.

1. S1: New deployment, ALB shows 502/503 errors.
   How to think: Check ALB target health → confirm health check path exists and returns 200 → verify container listens on the right port → check CloudWatch logs for startup errors.
2. S2: Tasks keep going to Stopped state right after starting.
   How to think: Look at the “stopped reason” in ECS → inspect container logs → common issues: wrong env vars, DB not reachable, port conflicts, or app crashes on boot.
3. S3: Database CPU is high and app feels slow.
   How to think: Check connection counts, slow queries, and indexing → consider connection pooling, query optimization, and potentially scaling RDS (larger instance or read replicas).
4. S4: Suddenly many 5xx errors during peak traffic.
   How to think: Check ECS service metrics (CPU/memory) → if tasks are maxed out, increase desired count or add auto scaling → ensure ALB health checks and timeouts are set correctly.
5. S5: A secret (like DB password) changed and app can’t connect.
   How to think: Update the value in Parameter Store → confirm the ECS task definition still references the correct parameter name → redeploy tasks so they pick up the new value.

6. S6: You need to add a new microservice (for example, reporting API).
   Approach: Create a new ECR repo and ECS task definition, a new ECS service, and (optionally) a new path rule on the ALB (like /reports/*). Wire it into CI/CD the same way as backend.
7. S7: You want a staging environment separate from production.
   Approach: Duplicate the stack in another VPC or another set of subnets with separate ECS cluster, RDS, and ALB. Use different DNS and separate CI/CD workflows pointing to staging resources.
8. S8: Frontend needs to call a third‑party API from the backend only.
   Approach: Keep the API key in Parameter Store, inject into backend task, and call the third‑party service from backend code. Frontend never sees the secret.
9. S9: You want zero‑downtime database migrations.
   Approach: Use migration tools (Prisma, Flyway, Liquibase) in a separate step or job before/with deployment, design migrations to be backward compatible, and roll out app changes after DB schema supports both versions.
10. S10: You want to explain cloud costs to a manager.
    Approach: Break it down: “We pay for compute (Fargate tasks), storage (RDS & ECR), traffic and security (ALB & NAT), and observability (CloudWatch). We can control each of these with scaling, instance sizes, and retention policies.”