⭐ If you like this project, give it a star on GitHub!

This project demonstrates a complete end-to-end DevOps workflow: from local development to cloud deployment using Node.js (Express), Docker, Terraform, AWS Fargate, and GitHub Actions.

It also uses Nix/Flakes to provide a fully reproducible development environment.

• 🟢 Node.js application using Express.
• ❄️ Nix devShell for consistent local development environment. Ensures consistent Node.js, Terraform, and AWS CLI versions using flake.nix.
• 🐳 Docker – Containerizes the Node.js Express app for local testing and cloud deployment.
• ☁️ Terraform – Manages AWS resources for the ECS/Fargate infrastructure.
• 🤖 CI/CD – GitHub Actions automate building, pushing, and deploying Docker images to ECS Fargate.
• 📊 CloudWatch Monitoring captures container logs for observability and debugging.

.
├── .github/
│   └── workflows/
│       ├── 01_provision_infra.yml    # Provisions AWS infrastructure via Terraform
│       └── 02_cicd_deployment.yml    # Builds, pushes, and deploys Docker image to ECS Fargate
│
├── docker/
│   └── Dockerfile                    # Build instructions for the Node.js + Express app
│
├── terraform/                        # Terraform IaC configuration
│   ├── main.tf                       # Core AWS resources
│   ├── variables.tf                  # Input variables for Terraform
│   ├── outputs.tf                    # Terraform outputs
│   ├── versions.tf                   # Required provider and Terraform versions
│   └── .terraform.lock.hcl           # Locked provider versions (auto-generated)
│
├── flake.nix                         # Nix devShell definition
├── flake.lock                        # Nix dependencies lock file
│
├── index.js                          # Express server entry point
├── package.json                      # Node.js dependencies and scripts
├── package-lock.json                 # Locked dependency versions
├── .gitignore                        # Ignored files and directories
├── LICENSE                           # MIT open-source license
├── README.md                         # project documentation
└── screenshots/                      # Project screenshots / demo images
    ├── ecr-repository.png            # Screenshot of ECR repository with pushed image
    ├── ecs-app-cluster.png           # Screenshot of ECS cluster with running task
    ├── gh-actions.png                # Screenshot of GitHub Actions CI/CD
    ├── local-nix-curl.png            # Screenshot of local app running in Nix devShell
    └── terraform-graph-graphviz.png  # Terraform resources graph generated via Graphviz

• Git – version control system
• Docker – container platform
• AWS account with access keys – required for deployment
• Nix with Flakes enabled (optional) – for a reproducible environment

Local Development

Enter the Nix devShell (optional):

nix develop

Install dependencies:

npm install

Start the application:

npm start

🐳 Or run the Dockerized application locally:

# Build Docker image
docker build -t simple-ecs-app -f docker/Dockerfile .

# Run Docker container
docker run -p 3000:3000 simple-ecs-app

# Access app in browser
http://localhost:3000

Endpoints available:

• / → Welcome message
• /api/hello → JSON message with current timestamp

☁️ Terraform Infrastructure Deployment

The Terraform backend is configured to use S3 for remote state management (terraform/versions.tf). This bucket must be created manually before the first deployment.

1. Create S3 State Bucket: Log in to your AWS Console and create an S3 bucket with the exact name specified in terraform/versions.tf:

fargate-nodejs-tf-state-bucket

1. Initialize Terraform: (Optional, for manual testing/review)

cd terraform
terraform init

🤖 CI/CD Deployment via GitHub Actions

This project uses GitHub Actions to automate the full CI/CD workflow:

1. Configure GitHub Secrets:

• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY

1. In GitHub → Actions, run:

• 01_provision_infra.yml (provisions AWS infra, First Run Only)
• 02_cicd_deployment.yml (builds & deploys image)

📊 Monitoring with CloudWatch

The ECS service sends container logs to AWS CloudWatch under the log group /ecs/simple-ecs-app. Logs are retained for 14 days and can be viewed in the AWS Console for debugging and monitoring.

Local App Running (Nix DevShell + curl) App running locally inside Nix devShell and accessible via curl.

GitHub Actions CI/CD pipeline in GitHub Actions.

Terraform Graph (Graphviz) Visual representation of Terraform resources and their dependencies using terraform graph + Graphviz.

ECS Cluster on AWS AWS ECS cluster running the task.

ECR Repository on AWS Docker image pushed to the AWS ECR repository.

✅ Result: A fully automated Node.js application deployed on AWS Fargate with Terraform-managed infrastructure and GitHub Actions CI/CD pipeline.

🛑 AWS Costs Warning

This project creates paid resources. Delete them after use to avoid charges:

cd terraform
terraform destroy -var="image_tag=latest"

Also, manually check in the AWS Console that all resources are deleted.