Deploying a Node.js Application on AWS ECS Fargate with Terraform and GitHub Actions

Introduction

Modern cloud-native applications require deployment processes that are automated, repeatable, and reliable. By combining Infrastructure as Code (IaC) with Continuous Deployment (CD), you can provision cloud infrastructure consistently while automating application deployments.

In this guide, you'll learn how to deploy a simple Node.js "Hello World" application on AWS Elastic Container Service (Amazon ECS) using AWS Fargate. The infrastructure is provisioned with Terraform, and GitHub Actions is used to automate the deployment pipeline.

This approach ensures that every code change is deployed consistently, reducing manual effort while improving deployment reliability and scalability.

Prerequisites

Before getting started, ensure you have the following prerequisites.

What Is AWS Fargate?

AWS Fargate is a serverless compute engine for Amazon Elastic Container Service (Amazon ECS) and Amazon Elastic Kubernetes Service (Amazon EKS).

Unlike traditional container deployments, AWS Fargate eliminates the need to provision or manage virtual machines. AWS automatically handles the underlying infrastructure, allowing you to focus solely on building and deploying your applications.

Key Features

• Fully managed container execution
• No server provisioning or management
• Automatic scaling based on workload
• Pay only for the compute and memory resources used
• Native integration with Amazon ECS and Amazon EKS

AWS Fargate is well suited for deploying containerized applications while minimizing operational overhead.

What Is Terraform?

Terraform is an open-source Infrastructure as Code (IaC) tool developed by HashiCorp.

Terraform enables you to define, provision, and manage infrastructure using declarative configuration files. By describing infrastructure as code, Terraform makes deployments reproducible, version-controlled, and easy to automate.

Terraform supports provisioning infrastructure across multiple cloud platforms, including:

• Amazon Web Services (AWS)
• Microsoft Azure
• Google Cloud
• Oracle Cloud
• Kubernetes
• VMware
• On-premises environments

Benefits of Terraform

• Infrastructure as Code (IaC)
• Automated infrastructure provisioning
• Version-controlled infrastructure
• Consistent deployments
• Multi-cloud support
• Reusable infrastructure configurations

Terraform simplifies infrastructure management by enabling repeatable deployments across development, testing, and production environments.

Step 1: Create a Simple Node.js Application

In this step, you'll create a basic Node.js application using the Express framework.

Express is a lightweight and flexible web framework for Node.js that simplifies building web applications and REST APIs. It provides a robust set of features for handling HTTP requests, routing, middleware, and application logic.

Project Structure

Create a project with the following directory structure:

hello-world-app/  
├── app.js  
├── Dockerfile  
├── package.json  
└── .gitignore  

This structure contains everything needed to build, containerize, and deploy the application.

Create the Application Entry Point

Create a file named app.js.

const express = require('express');  
const app = express();  
const PORT = process.env.PORT || 3000;

app.get('/', (req, res) => {  
  res.send('Hello World!');  
});

app.listen(PORT, () => {  
  console.log(`Server is running on port ${PORT}`);  
});  

Understanding the Application

This simple Express application performs the following tasks:

When the application starts successfully, you'll see output similar to:

Server is running on port 3000  

Create the package.json File

Create a file named package.json.

{  
  "name": "hello-world-app",  
  "version": "1.0.0",  
  "description": "Hello World Node.js app",  
  "main": "app.js",  
  "scripts": {  
    "start": "node app.js"  
  },  
  "dependencies": {  
    "express": "^4.17.1"  
  }  
}  

Understanding package.json

The package.json file contains the project's metadata, dependencies, and executable scripts.

In this project, Express is the only dependency required to run the web server.

Create the Dockerfile

Create a file named Dockerfile.

A Dockerfile contains the instructions required to package an application into a Docker image, making it portable and consistent across development, testing, and production environments.

FROM node:14

WORKDIR /usr/src/app

COPY package*.json ./

RUN npm install

COPY . .

EXPOSE 3000

CMD ["npm", "start"]  

Understanding the Dockerfile

The Dockerfile performs the following operations:

In the next step, you'll use Terraform to provision the required AWS infrastructure and configure GitHub Actions to automate deployments to AWS ECS Fargate.

Step 2: Configure AWS Infrastructure with Terraform

After creating and containerizing the Node.js application, the next step is to provision the AWS infrastructure required to run the application on Amazon ECS Fargate.

In this section, you'll use Terraform to automate the creation of AWS resources, including:

• Amazon ECS Cluster
• ECS Task Definition
• ECS Service
• IAM Execution Role
• Application Load Balancer (ALB)
• Target Group
• Listener
• Networking configuration

Using Terraform ensures that your infrastructure is version-controlled, reproducible, and easy to maintain.

Define Input Variables

Create a file named variables.tf.

This file defines reusable input variables that make the Terraform configuration flexible across different AWS environments.

variable "region" {  
  description = "The AWS region to create resources in"  
  type        = string  
  default     = "ap-south-1"  
}

variable "ecs_cluster_name" {  
  description = "The name of the ECS cluster"  
  type        = string  
}

variable "app_name" {  
  description = "The name of the application"  
  type        = string  
}

variable "vpc_id" {  
  description = "The ID of the VPC where resources will be created"  
  type        = string  
}

variable "subnet_ids" {  
  description = "A list of subnet IDs for the ECS service"  
  type        = list(string)  
}  

Understanding the Variables

These variables improve reusability by allowing the same Terraform code to be deployed across multiple environments.

Create the Main Terraform Configuration

Create a file named main.tf.

This file provisions all AWS resources required to deploy the application on Amazon ECS Fargate.

terraform {  
  backend "s3" {  
    bucket = "pavan-your-terraform-state-bucket"  
    key    = "ecs/hello-world-app/terraform.tfstate"  
    region = "ap-south-1"  
  }  
}

provider "aws" {  
  region = var.region  
}

resource "aws_ecs_cluster" "cluster" {  
  name = var.ecs_cluster_name  
}

resource "aws_iam_role" "ecs_task_execution_role" {  
  name = "ecsTaskExecutionRole"

  assume_role_policy = jsonencode({  
    Version = "2012-10-17"

    Statement = [  
      {  
        Effect = "Allow"

        Principal = {  
          Service = "ecs-tasks.amazonaws.com"  
        }

        Action = "sts:AssumeRole"  
      }  
    ]  
  })

  managed_policy_arns = [  
    "arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy"  
  ]  
}

resource "aws_ecs_task_definition" "task" {

  family             = var.app_name  
  network_mode       = "awsvpc"  
  cpu                = "256"  
  memory             = "512"

  execution_role_arn = aws_iam_role.ecs_task_execution_role.arn

  container_definitions = jsonencode([  
    {  
      name      = var.app_name

      image     = "567738737859.dkr.ecr.ap-south-1.amazonaws.com/hello-world-app:latest"

      essential = true

      portMappings = [  
        {  
          containerPort = 3000  
          hostPort      = 3000  
        }  
      ]  
    }  
  ])  
}

resource "aws_ecs_service" "service" {

  name            = var.app_name  
  cluster         = aws_ecs_cluster.cluster.id  
  task_definition = aws_ecs_task_definition.task.arn

  desired_count = 1  
  launch_type   = "FARGATE"

  network_configuration {

    subnets          = var.subnet_ids

    assign_public_ip = true

    security_groups  = ["sg-098d8e07dc8df4f85"]

  }

  load_balancer {

    target_group_arn = aws_lb_target_group.app_target_group.arn

    container_name   = var.app_name

    container_port   = 3000

  }

}

resource "aws_lb" "app_lb" {

  name               = "${var.app_name}-lb"

  internal           = false

  load_balancer_type = "application"

  security_groups    = ["sg-098d8e07dc8df4f85"]

  subnets            = var.subnet_ids

}

resource "aws_lb_target_group" "app_target_group" {

  name        = "${var.app_name}-tg"

  port        = 3000

  protocol    = "HTTP"

  vpc_id      = var.vpc_id

  target_type = "ip"

}

resource "aws_lb_listener" "app_listener" {

  load_balancer_arn = aws_lb.app_lb.arn

  port              = "80"

  protocol          = "HTTP"

  default_action {

    type             = "forward"

    target_group_arn = aws_lb_target_group.app_target_group.arn

  }

}  

Terraform Configuration Overview

The main.tf file provisions the following AWS resources.

Configure Variable Values

Create a file named terraform.tfvars.

This file provides the values for the variables declared in variables.tf.

Replace the placeholder values with resources from your AWS environment.

region = "ap-south-1"

ecs_cluster_name = "cluster-name"

app_name = "app_name"

vpc_id = "vpc-id"

subnet_ids = [  
  "subnet-id-1",  
  "subnet-id-2"  
]  

Variable Definitions

Step 3: Configure GitHub Actions for Continuous Deployment

GitHub Actions is GitHub's built-in Continuous Integration and Continuous Deployment (CI/CD) platform that enables you to automate software workflows directly from your GitHub repository.

Using GitHub Actions, you can automatically build, test, and deploy your application whenever code changes are pushed to a repository.

In this project, GitHub Actions automates the following tasks:

• Build the Docker image
• Push the image to Amazon Elastic Container Registry (Amazon ECR)
• Provision or update AWS infrastructure using Terraform
• Deploy the application to Amazon ECS Fargate

This automation ensures that every push to the main branch results in a consistent and reliable deployment.

Create the GitHub Actions Workflow

Inside the project root, create the following directory structure:

.github/  
└── workflows/  
    └── deploy.yml  

The deploy.yml file defines the Continuous Deployment workflow.

GitHub Actions Workflow (deploy.yml)

name: Deploy to ECS

on:  
  push:  
    branches:  
      - main

jobs:  
  build:

    runs-on: ubuntu-latest

    steps:

      - name: Checkout code  
        uses: actions/checkout@v2

      - name: Set up Docker Buildx  
        uses: docker/setup-buildx-action@v1

      - name: Configure AWS credentials  
        uses: aws-actions/configure-aws-credentials@v1

        with:  
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}  
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}  
          aws-region: ${{ secrets.AWS_DEFAULT_REGION }}

      - name: Log in to Amazon ECR  
        id: ecr-login

        uses: aws-actions/amazon-ecr-login@v1

        with:  
          registry-type: "private"  
          mask-password: true

      - name: Build, tag, and push Docker image to Amazon ECR

        env:  
          ECR_REGISTRY: 567738737859.dkr.ecr.ap-south-1.amazonaws.com  
          ECR_REPOSITORY: hello-world-app  
          IMAGE_TAG: latest

        run: |  
          docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .

          docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG

      - name: Download Terraform  
        uses: hashicorp/setup-terraform@v1

        with:  
          terraform_version: 1.0.0

      - name: Terraform Init  
        run: terraform init

        working-directory: ./terraform

      - name: Terraform Apply  
        run: terraform apply -auto-approve

        working-directory: ./terraform

      - name: Terraform Destroy  
        run: terraform destroy -auto-approve

        working-directory: ./terraform  

Workflow Overview

The workflow is automatically triggered whenever code is pushed to the main branch.

It performs the following sequence of tasks.

Configure GitHub Secrets

To allow GitHub Actions to authenticate with AWS securely, store your AWS credentials as GitHub Secrets.

Navigate to your GitHub repository:

Settings → Secrets and Variables → Actions

Create the following repository secrets:

Using GitHub Secrets ensures that sensitive credentials are encrypted and never exposed within the workflow file.

Step 4: Create an Amazon ECR Repository

Amazon Elastic Container Registry (Amazon ECR) is a fully managed container registry service that stores Docker and OCI-compatible container images.

Before deploying the application to Amazon ECS Fargate, you must create an Amazon ECR repository where the Docker image will be stored.

Create the Repository Using AWS CLI

Run the following command:

aws ecr create-repository \  
--repository-name hello-world-app  

This command creates a private Amazon ECR repository named hello-world-app.

Expected Output

After successful execution, the AWS CLI returns information similar to the following:

• Repository ARN
• Repository URI
• Repository Name
• Registry ID
• Repository Creation Time

The Repository URI is used later when building and pushing Docker images.

Push the Docker Image to Amazon ECR

Once the repository has been created, the Docker image can be pushed to Amazon ECR.

In this project, no manual steps are required because the GitHub Actions workflow created in the previous step automatically performs the following actions whenever code is pushed to the main branch:

1. Builds the Docker image.
2. Tags the image with the Amazon ECR repository URI.
3. Authenticates with Amazon ECR.
4. Pushes the image to the repository.

This automated process ensures that the latest application image is always available for deployment to Amazon ECS Fargate.

Step 5: Manage AWS Secrets in GitHub

To securely authenticate GitHub Actions with AWS, sensitive information such as AWS access keys should never be stored directly in your source code or workflow files.

Instead, GitHub provides Repository Secrets, which securely encrypt sensitive credentials and make them available during workflow execution.

The GitHub Actions workflow references these secrets through environment variables whenever it needs to interact with AWS services such as Amazon ECR, Amazon ECS, or Terraform.

Add AWS Secrets to GitHub

Open your GitHub repository.

https://github.com/\<your-username>/hello-world-app  

Navigate to:

Settings → Secrets and variables → Actions

Create the following repository secrets.

These secrets are referenced within the GitHub Actions workflow using:

${{ secrets.AWS_ACCESS_KEY_ID }}

${{ secrets.AWS_SECRET_ACCESS_KEY }}  

This approach keeps your AWS credentials secure while allowing GitHub Actions to authenticate with AWS during deployment.

Why Use GitHub Secrets?

GitHub Secrets provide several security benefits.

With this configuration, GitHub Actions can securely:

• Authenticate with AWS
• Push Docker images to Amazon ECR
• Provision infrastructure using Terraform
• Deploy applications to Amazon ECS Fargate

Step 6: Initialize Git and Push the Project to GitHub

After creating the application and Terraform configuration, initialize a Git repository and push the project to GitHub.

Initialize the Repository

Navigate to the project directory.

cd hello-world-app  

Initialize Git.

git init  

Add the GitHub repository as the remote origin.

git remote add origin https://github.com/your-username/hello-world-app.git  

Stage all project files.

git add .  

Create the initial commit.

git commit -m "Initial commit: Node.js app, Dockerfile, and Terraform configuration"  

Rename the default branch to main.

git branch -M main  

Push the project to GitHub.

git push -u origin main  

After these commands complete successfully, the complete project will be available in your GitHub repository.

Add the GitHub Actions Workflow

Create the workflow directory.

mkdir -p .github/workflows  

Create the deployment workflow.

cat \<\<EOF > .github/workflows/deploy.yml  
# Add the GitHub Actions workflow content here (as shown in Step 3)  
EOF  

Commit the workflow.

git add .github/workflows/deploy.yml

git commit -m "Add GitHub Actions workflow for ECS deployment"

git push  

After the workflow file is pushed to GitHub, every push to the main branch automatically triggers the deployment pipeline.

Step 7: Configure the Terraform Remote Backend

Terraform maintains a state file that records all infrastructure resources managed by Terraform.

For production environments, it is recommended to store the state file in a remote backend rather than locally.

Using a remote backend improves collaboration, consistency, and reliability across teams.

Why Use a Remote Backend?

A remote backend offers several advantages over storing the Terraform state locally.

Configure an Amazon S3 Backend

Update the main.tf file with the following backend configuration.

terraform {

  backend "s3" {

    bucket = "pavan-your-terraform-state-bucket"

    key = "ecs/hello-world-app/terraform.tfstate"

    region = "ap-south-1"

  }

}  

This configuration instructs Terraform to store its state remotely in an Amazon S3 bucket.

Understanding the Backend Configuration

Using an S3 backend enables multiple users and CI/CD pipelines to work with the same infrastructure state safely.

Understanding terraform.tfstate

The terraform.tfstate file is a critical component of Terraform.

It stores information about every infrastructure resource managed by Terraform, including resource identifiers, attributes, and dependencies.

Terraform automatically creates and updates this file whenever commands such as terraform apply, terraform destroy, or terraform refresh are executed.

When using an Amazon S3 backend, the state file is not stored locally. Instead, Terraform automatically uploads and manages it within the configured S3 bucket.

For this configuration, the state file is stored at:

Bucket:  
pavan-your-terraform-state-bucket

Object Key:  
ecs/hello-world-app/terraform.tfstate  

No manual creation or modification of the terraform.tfstate file is required, as Terraform manages it automatically throughout the infrastructure lifecycle.

Step 8: Deploy the Application

After completing the application development and infrastructure setup, you're ready to deploy the Node.js application to AWS ECS Fargate.

At this stage, the deployment process is fully automated through GitHub Actions. Every time code is pushed to the main branch, GitHub Actions builds the application, pushes the Docker image to Amazon ECR, provisions or updates the infrastructure using Terraform, and deploys the latest version to Amazon ECS Fargate.

Deployment Checklist

Before triggering the deployment, verify that the following components are correctly configured.

Once these prerequisites are complete, you can deploy the application.

Step 1: Push Your Changes to GitHub

Commit your latest changes.

git add .

git commit -m "Deploy Node.js application"

git push origin main  

Pushing code to the main branch automatically triggers the GitHub Actions deployment workflow.

Step 2: Monitor the GitHub Actions Workflow

Open your GitHub repository and navigate to:

Actions

Locate the workflow named:

Deploy to ECS  

Select the latest workflow run to monitor the deployment process.

The workflow executes each deployment stage sequentially and displays detailed logs for every step.

Step 3: Review Workflow Logs

During execution, GitHub Actions displays real-time logs for each deployment stage.

Typical workflow stages include:

• Checking out the repository
• Configuring AWS credentials
• Authenticating with Amazon ECR
• Building the Docker image
• Pushing the Docker image to Amazon ECR
• Initializing Terraform
• Applying Terraform configuration
• Deploying the ECS service

Review the logs carefully to identify any warnings or deployment errors.

Common issues include:

Address any reported errors before re-running the workflow.

Step 4: Verify the Deployment

After the workflow completes successfully, verify that the application has been deployed correctly.

You can validate the deployment using one or more of the following methods.

Access the Application

Open the Application Load Balancer (ALB) endpoint in your browser.

If the deployment is successful, the application should display:

Hello World!  

Verify the ECS Service

In the AWS Management Console, navigate to:

Amazon ECS  
    └── Cluster  
          └── Service  

Verify that:

• The ECS service is running.
• The desired task count matches the running task count.
• The deployment status is Healthy.
• No task failures are reported.

Verify the Docker Image

Navigate to:

Amazon ECR  

Confirm that the latest Docker image has been successfully pushed to the repository.

Verify the Infrastructure

Navigate to:

AWS CloudFormation (if applicable)

or

Terraform State  

Confirm that all required infrastructure resources were created successfully.

End-to-End Deployment Workflow

The complete deployment process follows the sequence below:

Developer  
      │  
      ▼  
Push Code to GitHub  
      │  
      ▼  
GitHub Actions  
      │  
      ├── Checkout Source Code  
      ├── Build Docker Image  
      ├── Push Image to Amazon ECR  
      ├── Initialize Terraform  
      ├── Apply Infrastructure Changes  
      ▼  
Amazon ECS Fargate  
      │  
      ▼  
Application Running Behind  
Application Load Balancer  

Conclusion

In this guide, you successfully built an end-to-end deployment pipeline for a containerized Node.js application using modern cloud-native technologies.

By combining Terraform, Docker, GitHub Actions, Amazon Elastic Container Registry (Amazon ECR), and Amazon ECS Fargate, you created a deployment workflow that is automated, secure, scalable, and easy to maintain.

Key Takeaways

Benefits of This Architecture

• Fully automated Continuous Deployment (CD)
• Infrastructure managed as code
• Secure credential management using GitHub Secrets
• Scalable serverless container platform
• Version-controlled infrastructure
• Reproducible deployments across environments
• Simplified operations with minimal infrastructure management

This deployment pipeline provides a strong foundation for modern cloud-native applications and can be extended to support advanced production features such as multi-environment deployments, blue/green deployments, rolling updates, monitoring, logging, auto scaling, and security best practices.