I wanted a hands-on project that ties together networking, compute, and Infrastructure as Code (IaC), and a static website on EC2 is a good small-scale way to do that. This walkthrough shows how I built it with Terraform, from an empty folder to a live site, with no clicking around the AWS console.

What we’re building

A single Nginx web server on EC2, inside a custom VPC, with a fixed public IP, all defined in Terraform.

Browser → Elastic IP → Internet Gateway → Route Table → Public Subnet
        → Security Group (port 80) → EC2 → Nginx → index.html

Resources created: VPC, public subnet, internet gateway, route table and association, security group, EC2 instance, and an Elastic IP.

Prerequisites

• An AWS account
• AWS CLI installed and configured (aws configure)
• Terraform 1.5 or newer installed
• A code editor (I used VS Code)

Check your setup:

terraform -version
aws sts get-caller-identity

Step 1: Create the project folder

mkdir tf-static-site
cd tf-static-site

Create these files inside it:

tf-static-site/
├── main.tf
├── outputs.tf
└── user_data.sh

Step 2: Configure the provider

Open main.tf and start with the Terraform block and AWS provider:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = "us-east-1"
}

Pinning the provider version keeps your runs reproducible. A new provider release can’t quietly change behavior.

Step 3: Look up the latest Amazon Linux AMI

Instead of hardcoding an AMI ID, which differs per region and goes stale, ask AWS for the current one:

data "aws_ssm_parameter" "al2023" {
  name = "/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64"
}

A data source reads existing information. It creates nothing.

Step 4: Build the network

A server needs somewhere to live. I built the network layer by layer.

The VPC, your own isolated network:

resource "aws_vpc" "site" {
  cidr_block           = "10.0.0.0/16"
  enable_dns_hostnames = true

  tags = {
    Name = "static-site-vpc"
  }
}

The public subnet, a slice of the VPC in one Availability Zone:

resource "aws_subnet" "public" {
  vpc_id                  = aws_vpc.site.id
  cidr_block              = "10.0.1.0/24"
  availability_zone       = "us-east-1a"
  map_public_ip_on_launch = true

  tags = {
    Name = "static-site-public"
  }
}

The internet gateway, the VPC’s door to the internet:

resource "aws_internet_gateway" "site" {
  vpc_id = aws_vpc.site.id
}

The route table and association, which actually make the subnet public:

resource "aws_route_table" "public" {
  vpc_id = aws_vpc.site.id

  route {
    cidr_block = "0.0.0.0/0"
    gateway_id = aws_internet_gateway.site.id
  }
}


resource "aws_route_table_association" "public" {
  subnet_id      = aws_subnet.public.id
  route_table_id = aws_route_table.public.id
}

The route says “send all non-local traffic to the internet gateway,” and the association attaches that rule to the subnet. A gateway on its own does nothing until a route points to it.

Step 5: Add the security group

The security group is a stateful firewall. I only opened what the website needs, which is port 80:

resource "aws_security_group" "site" {
  name        = "ozort-static-site-sg"
  description = "HTTP from anywhere"
  vpc_id      = aws_vpc.site.id

ingress {
    from_port   = 80
    to_port     = 80
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }

egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

Ingress allows web traffic in. Egress allows the server to reach out, which it needs to download Nginx. There’s no port 22, which follows the principle of least privilege.

Step 6: Write the bootstrap script

This is the configuration layer. Terraform builds the server, and this script sets up what runs inside it. Put it in user_data.sh:

#!/bin/bash
set -euxo pipefail

dnf install -y nginx

cat > /usr/share/nginx/html/index.html <<'HTML'
<h1>Deployed with Terraform</h1>
<p>Built by Bob (Ozort)</p>
HTML

systemctl enable --now nginx

Two details matter:

• #!/bin/bash must be the very first line, because that's how cloud-init recognises a script.
• Save the file with LF line endings, not Windows CRLF. In VS Code, click CRLF in the bottom-right corner and switch it to LF.

systemctl enable --now nginx starts Nginx immediately and again after every reboot.

Step 7: Create the EC2 instance

resource "aws_instance" "site" {
  ami                    = data.aws_ssm_parameter.al2023.value
  instance_type          = "t3.micro"
  subnet_id              = aws_subnet.public.id
  vpc_security_group_ids = [aws_security_group.site.id]

  user_data                   = file("${path.module}/user_data.sh")
  user_data_replace_on_change = true

  tags = {
    Name = "static-site"
  }
}

user_data only runs on the instance's first boot. user_data_replace_on_change = true tells Terraform to replace the instance whenever the script changes, so the server always matches the code. That's the immutable infrastructure pattern: replace rather than patch.

Step 8: Attach an Elastic IP

Without one, the instance’s public IP changes every time it stops and starts:

resource "aws_eip" "site" {
  instance   = aws_instance.site.id
  domain     = "vpc"
  depends_on = [aws_internet_gateway.site]
}

depends_on makes sure the internet gateway exists before the address is attached.

Step 9: Output the URL

In outputs.tf:

output "site_url" {
  value = "http://${aws_eip.site.public_ip}"
}

Step 10: Deploy

terraform fmt
terraform init
terraform validate
terraform plan
terraform apply

• init downloads the AWS provider.
• validate checks your syntax.
• plan shows what Terraform is about to create, so you can review it before anything changes.
• apply builds it. Type yes when prompted.

Terraform reads the references between resources and works out the build order itself. It creates the VPC first, then the subnet, then the instance, then the Elastic IP. You never specify that order.

Step 11: Verify

terraform output site_url
curl.exe http://<your-elastic-ip>

Give the instance a couple of minutes after it shows running, because the bootstrap script needs time to install Nginx. Then open the URL in your browser (use http://, not https://) and the page loads.

Step 12: Clean up

terraform destroy

Everything Terraform created is removed. Since the whole project is code, you can rebuild it any time with one command.

How it all comes together

What this project taught me

• Provisioning and configuration are separate concerns. Terraform builds the infrastructure, and the bootstrap script configures the software.
• A subnet is only public if it has a route to an internet gateway. The gateway alone isn’t enough.
• Terraform builds a dependency graph. References between resources decide the order, not the order of the code.
• user_data runs once. Changing the script means replacing the instance.
• Least privilege starts at the firewall. Open only the ports the service needs.

If you’ve spent any time reading CloudFront + S3 tutorials, you’ve probably run into both terms Origin Access Identity (OAI) and Origin Access Control (OAC) often without a clear explanation of why there are two mechanisms doing what sounds like the same job. This article breaks down the actual difference, why AWS pushed one out in favor of the other, and what the switch looks like in practice.

The problem both of them solve

If you’re serving a static site (or any content) from S3 through CloudFront, the naive approach is to make the S3 bucket public. That works, but it means anyone who finds your bucket’s direct URL can bypass CloudFront entirely skipping your caching, your HTTPS enforcement, any WAF rules, all of it. The bucket should stay private, and only CloudFront should be able to read from it.

OAI and OAC are AWS’s two answers to that same problem: “let CloudFront read this private bucket, and nothing else.”

Origin Access Identity (OAI) — the original approach

OAI works by creating a special CloudFront “identity” essentially a virtual user that you then attach to your distribution and grant read access to in your bucket policy. Your policy’s Principal ends up pointing at this identity's canonical user ID rather than at CloudFront directly.

It works, and for years it was the only option. But it has real limitations:

• It didn’t support S3 server-side encryption with KMS (SSE-KMS)
• It didn’t support S3 Object Lambda
• It didn’t support all S3 regions, including newer opt-in regions launched after a certain point
• It didn’t support dynamic requests to S3 like PUT and DELETE only reads
• It relies on an older authentication mechanism rather than AWS’s standard signing approach

That last point matters more than it sounds. OAI doesn’t cryptographically sign each request it identifies itself via a fixed identity, which is a weaker security model than what most other AWS services use.

Origin Access Control (OAC) — the replacement

OAC is the modern replacement for OAI, and it uses AWS Signature Version 4 (SigV4) for authentication, the same standard signing method used across AWS services. Every request CloudFront makes to your bucket is individually signed, rather than relying on a static identity.

AWS explicitly recommends OAC because it supports all Amazon S3 buckets in all AWS regions (including opt-in regions launched after December 2022), S3 server-side encryption with KMS, and dynamic requests like PUT and DELETE to S3 none of which OAI handles, or which it only handles with workarounds.

This isn’t a marginal improvement it’s AWS closing every gap OAI had, plus adding proper request signing.

Is OAI actually deprecated?

Yes, AWS’s own language has shifted from “OAC is recommended” to calling OAI deprecated outright. AWS’s guidance now states plainly that origin access identity has been deprecated in favor of origin access control, and that distributions using OAI should be migrated to OAC to benefit from enhanced security controls. Security posture tools like Datadog’s cloud security rules flag OAI usage specifically for this reason, recommending migration to OAC for the same reasons: enhanced security features including signed requests, granular permissions, and support for IAM policies, plus broader compatibility across S3 and custom origins.

If you’re starting a new project today, there’s no real argument for choosing OAI over OAC. It’s not a stylistic preference one is actively being phased out.

What OAC costs you: a little extra complexity

OAC isn’t strictly “easier” than OAI: it asks for more precision, in exchange for closing the gaps above. The tradeoffs summarize cleanly:

The two things worth calling out on the OAC side, since they trip people up during migration:

1. When using OAC with an S3 origin, your bucket’s Object Ownership setting must be “Bucket owner enforced” (the default for new buckets) if you need ACLs for some reason, you’d use “Bucket owner preferred” instead.
2. If your S3 bucket is configured as a website endpoint (S3’s own static website hosting feature) rather than a regular bucket, you can’t use OAC or OAI, for that matter since a website-endpoint origin has to be added to CloudFront as a custom origin instead. This is actually a good argument for using a plain S3 bucket behind CloudFront + OAC rather than S3’s built-in website hosting mode, if you’re setting this up fresh.

What the switch actually looks like in Terraform

Concretely, moving from OAI to OAC touches two resources.

Before (OAI):

hcl

resource "aws_cloudfront_origin_access_identity" "oai" {}

# in the distribution's origin block:
s3_origin_config {
  origin_access_identity = aws_cloudfront_origin_access_identity.oai.cloudfront_access_identity_path
}

# in the bucket policy:
Principal = {
  AWS = aws_cloudfront_origin_access_identity.oai.iam_arn
}

After (OAC):

hcl

resource "aws_cloudfront_origin_access_control" "oac" {
  name                              = "my-site-oac"
  origin_access_control_origin_type = "s3"
  signing_behavior                  = "always"
  signing_protocol                  = "sigv4"
}

# in the distribution's origin block:
origin_access_control_id = aws_cloudfront_origin_access_control.oac.id

# in the bucket policy:
Principal = { Service = "cloudfront.amazonaws.com" }
Condition = {
  StringEquals = {
    "AWS:SourceArn" = aws_cloudfront_distribution.this.arn
  }
}

The meaningful shift in the bucket policy: instead of trusting a specific identity (the OAI), you’re trusting the CloudFront service generally, then scoping that trust down to one exact distribution ARN via the Condition block. That Condition is what stops any other CloudFront distribution (yours or anyone else's) from being able to use this same trust relationship.

If you’re migrating an already-live distribution rather than building fresh, don’t skip terraform plan here because the origin's configuration shape changes and the bucket policy's principal changes entirely, this is the kind of change worth reading through in full rather than applying on faith.

So which one should you actually use?

OAC, without much debate, for anything new. It closes every functional gap OAI had, uses a stronger authentication model, works with more origin types, and is where AWS is explicitly steering everyone. The only reason you’d still see OAI in a codebase is legacy — something built before OAC existed, or copied from a tutorial that hasn’t been updated. If you’re maintaining one of those, migrating is a well-documented, low-risk change, and AWS’s own security tooling will likely flag it for you if it hasn’t already.

If you’ve never used Terraform to deploy anything on AWS before, this is a good first real project small enough to finish in one sitting, but it touches S3, CloudFront, IAM policies, and remote state, which are things you’ll use in almost everything else you build later.

We’re going to build a static site from scratch: a private S3 bucket serving content through CloudFront over HTTPS, with a working 404 page.

What you’ll need before starting

• An AWS account, with credentials configured locally. If you haven’t done this yet, run aws configure and enter your access key, secret key, and default region.
• Terraform installed (version 1.x).
• The AWS CLI installed (you’ll use it for one manual step near the end).
• Basic comfort in a terminal. You don’t need to know HCL (Terraform’s language) yet we’ll explain each block as it comes up.

Step 1 — Set up your project folder

Create a folder and a website/ subfolder for your actual site content:

mkdir static-site-project && cd static-site-project
mkdir website

Drop a basic website/index.html and website/error.html in there for now ; even a one-line placeholder is fine, we'll come back to real content later. What matters right now is that the folder exists, because Terraform will read from it.

Step 2 — Set up remote state (before you write any Terraform)

This is the part beginners usually skip, and it bites them later. By default, Terraform stores its “state” (a record of what it created) in a local file on your machine. That’s fine solo, but it breaks the moment you work from a second machine or with anyone else and it’s also just safer to have state somewhere durable.

Create an S3 bucket and a DynamoDB table for this, once, outside of Terraform:

aws s3api create-bucket --bucket your-terraform-state-bucket --region us-east-1
aws dynamodb create-table \
  --table-name terraform-locks \
  --attribute-definitions AttributeName=LockID,AttributeType=S \
  --key-schema AttributeName=LockID,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST

Replace your-terraform-state-bucket with something unique to you S3 bucket names are global across every AWS account, so a generic name will already be taken.

Why can’t Terraform create this bucket and table itself? Because the backend has to exist before Terraform can talk to it. it’s a chicken-and-egg problem, so this one step happens outside your Terraform config.

Step 3 — Write provider.tf

This file tells Terraform which cloud provider to use and where to store its state.

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.0"
    }
  }

  backend "s3" {
    bucket         = "your-terraform-state-bucket"
    key            = "static-site/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-locks"
    encrypt        = true
  }
}

provider "aws" {
  region = var.aws_region
}

Swap in the bucket and table names from Step 2. Note that this block can’t use a variable for the region backend blocks are evaluated before Terraform has loaded your variables, so it has to be a literal string here.

Step 4 — Write variables.tf

Variables are Terraform’s way of letting you parameterize your config instead of hardcoding values.

variable "bucket_name" {
  description = "Name of the S3 bucket to host the website. Must be globally unique."
  type        = string
}

variable "website_index_document" {
  description = "The default page CloudFront serves at the site root"
  type        = string
  default     = "index.html"
}

variable "aws_region" {
  description = "AWS region to deploy into"
  type        = string
  default     = "us-east-1"
}

Notice bucket_name has no default you're required to supply it yourself every time you run Terraform. This is deliberate: since bucket names must be globally unique, a default value would just mean "works for me, fails for you."

Step 5 — Start main.tf: the S3 bucket

This is where the real infrastructure gets defined. Start with just the bucket:

resource "aws_s3_bucket" "website_bucket" {
  bucket = var.bucket_name
}

That’s it for now. one resource, referencing the variable you just defined.

Step 6 — Lock the bucket down from public access

Even though we’re about to make this bucket serve a public website, the bucket itself should never be directly public only reachable through CloudFront. Add:

resource "aws_s3_bucket_public_access_block" "website_bucket" {
  bucket = aws_s3_bucket.website_bucket.id

  block_public_acls   = true
  ignore_public_acls  = true
  block_public_policy     = false
  restrict_public_buckets = false
}

The last two are false on purpose. We're about to attach a bucket policy that grants access to CloudFront specifically if those were true, that policy would be blocked too.

Step 7 — Upload your website files

Rather than writing one resource per file (which means editing main.tf every time you add a page), loop over everything in your website/ folder:

resource "aws_s3_object" "website_files" {
  for_each = fileset("website/", "**")

  bucket = aws_s3_bucket.website_bucket.id
  key    = each.value
  source = "website/${each.value}"
  etag   = filemd5("website/${each.value}")

  content_type = lookup(
    {
      html = "text/html"
      css  = "text/css"
      js   = "application/javascript"
      png  = "image/png"
      jpg  = "image/jpeg"
      svg  = "image/svg+xml"
    },
    lower(element(split(".", each.value), length(split(".", each.value)) - 1)),
    "application/octet-stream"
  )
}

A few things worth understanding here, since this block does a lot:

• fileset("website/", "**") lists every file in that folder, recursively.
• for_each creates one aws_s3_object per file found add a new file, and next apply picks it up automatically.
• etag = filemd5(...) is how Terraform knows a file changed if the file's content hash is different, Terraform re-uploads it.
• The content_type lookup sets the correct MIME type based on file extension. Without this, S3 defaults to a generic binary type, and your browser may try to download your HTML instead of rendering it.

Step 8 — Create Origin Access Control (OAC)

This is the mechanism that lets CloudFront read from your private bucket without the bucket being public.

resource "aws_cloudfront_origin_access_control" "website_oac" {
  name                              = "${var.bucket_name}-oac"
  description                       = "OAC for ${var.bucket_name} static website"
  origin_access_control_origin_type = "s3"
  signing_behavior                  = "always"
  signing_protocol                  = "sigv4"
}

You’ll see older tutorials use “Origin Access Identity” (OAI) instead OAC is the newer, AWS-recommended approach, so that’s what we’re using here.

Step 9 — The CloudFront distribution

This is the biggest block. it’s what actually serves your site to visitors.

resource "aws_cloudfront_distribution" "cloudfront_distribution" {
  origin {
    domain_name              = aws_s3_bucket.website_bucket.bucket_regional_domain_name
    origin_id                = var.bucket_name
    origin_access_control_id = aws_cloudfront_origin_access_control.website_oac.id
  }

  enabled             = true
  is_ipv6_enabled     = true
  default_root_object = var.website_index_document

  default_cache_behavior {
    allowed_methods  = ["GET", "HEAD"]
    cached_methods   = ["GET", "HEAD"]
    target_origin_id = var.bucket_name

    forwarded_values {
      query_string = false
      cookies {
        forward = "none"
      }
    }

    min_ttl                = 0
    default_ttl             = 3600
    max_ttl                  = 86400
    compress                = true
    viewer_protocol_policy = "redirect-to-https"
  }

  custom_error_response {
    error_code         = 404
    response_code      = 404
    response_page_path = "/error.html"
  }

  custom_error_response {
    error_code         = 403
    response_code      = 404
    response_page_path = "/error.html"
  }

  viewer_certificate {
    cloudfront_default_certificate = true
  }

  restrictions {
    geo_restriction {
      restriction_type = "none"
    }
  }

  tags = {
    Name        = "Cloudfront Distribution"
    Environment = "Dev"
  }
}

Breaking down the pieces beginners usually ask about:

• origin: Points CloudFront at your S3 bucket, using the OAC from Step 8.
• default_root_object : what to serve when someone visits the bare domain (no path).
• viewer_protocol_policy = "redirect-to-https" : anyone hitting HTTP gets bounced to HTTPS automatically.
• default_ttl = 3600 : CloudFront caches responses for an hour before re-checking S3. This matters later when you update content and don't see the change immediately.
• Both custom_error_response blocks matter. You might expect only a 404 rule is needed for a missing page, but S3 actually returns 403 (not 404) for a missing object when your bucket policy doesn't grant s3:ListBucket which is the case here. Without the 403 rule too, most broken links would bypass your error page entirely.
• viewer_certificate { cloudfront_default_certificate = true } : uses CloudFront's shared default certificate. Fine for testing; if you want a custom domain later, this block changes.

Step 10 — The bucket policy

This is what actually grants CloudFront permission to read your bucket:

resource "aws_s3_bucket_policy" "website_bucket_policy" {
  bucket = aws_s3_bucket.website_bucket.id

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Sid      = "AllowCloudFrontServicePrincipalReadOnly"
        Effect   = "Allow"
        Action   = "s3:GetObject"
        Resource = "${aws_s3_bucket.website_bucket.arn}/*"
        Principal = {
          Service = "cloudfront.amazonaws.com"
        }
        Condition = {
          StringEquals = {
            "AWS:SourceArn" = aws_cloudfront_distribution.cloudfront_distribution.arn
          }
        }
      }
    ]
  })
}

The important part is the Condition block it scopes this permission to this specific distribution, not to any CloudFront distribution anyone might create. Without it, any AWS account's CloudFront distribution could technically read your bucket, which is not what you want.

Step 11 — Outputs

Add an outputs.tf so Terraform tells you the useful values after it finishes:

output "s3_bucket_name" {
  value = aws_s3_bucket.website_bucket.id
}

output "cloudfront_distribution_domain_name" {
  value = aws_cloudfront_distribution.cloudfront_distribution.domain_name
}

output "cloudfront_distribution_id" {
  value       = aws_cloudfront_distribution.cloudfront_distribution.id
  description = "Useful for manually running aws cloudfront create-invalidation if needed"
}

You’ll actually use cloudfront_distribution_id later, so don't skip this file.

Step 12 — Deploy it

Now that every file is in place:

terraform init
terraform plan -var="bucket_name=your-unique-bucket-name"

Read the plan output before continuing, it should show everything being created, nothing being destroyed (since this is a first deploy). If it looks right:

terraform apply -var="bucket_name=your-unique-bucket-name"

Type yes when prompted. After a minute or two, Terraform prints your three outputs. Copy the cloudfront_distribution_domain_name value and open it in a browser that's your live site.

To access your error.html you’d have to add /error at the end of your cloudfront domain i.e cloudfront_distribution_domain_name/error

Step 13 — Updating your site later

Edit or add a file in website/, then run apply again with the same bucket_name variable. Terraform re-uploads only what changed.

One thing that surprises beginners: your change might not show up immediately, because CloudFront is still serving a cached response (remember default_ttl = 3600, one hour). You have two options:

• Wait it out: after an hour, the cache expires on its own.
• Force it now, using the distribution ID from your outputs:

terraform output cloudfront_distribution_id
aws cloudfront create-invalidation --distribution-id <the-id-you-just-got> --paths "/*"

Step 14 — Tearing it down

When you’re done experimenting:

terraform destroy -var="bucket_name=your-unique-bucket-name"

This removes everything Terraform created the bucket, its contents, the distribution, the policy, and the OAC. Your remote state bucket and DynamoDB table from Step 2 are untouched, since those live outside this config.

What you just learned, in one paragraph

You built a private S3 bucket that’s only reachable through a specific CloudFront distribution (not the public internet), using Origin Access Control rather than making the bucket itself public which is the pattern you’ll want for basically every static site you host on AWS going forward. You also touched remote state, variable-driven configuration, dynamic resource loops with for_each, and CloudFront's caching and error-handling behavior all of which come up constantly in real infrastructure work, not just this one project.

A few weeks ago I set out to do something that should have taken an afternoon: host a static personal site on S3, put CloudFront in front of it for HTTPS, and call it done. Terraform makes this look trivial in every tutorial a bucket, a distribution, a couple of aws_s3_object blocks, apply, ship it.

It mostly is that simple. But the gap between “it plans clean” and “it’s actually production-sane” is where the real learning happened, and that gap is what I want to walk through.

The starting point

The first version worked. S3 bucket, CloudFront distribution, an Origin Access Identity (OAI) so the bucket stayed private, a bucket policy scoped to that OAI. Two files uploaded as individual aws_s3_object resources: index.html and error.html. It deployed, the site loaded, green checkmark, move on.

Except a few things were quietly wrong, and none of them would have shown up until they mattered.

OAI is legacy and the fix isn’t a one-line swap

AWS has been steering people toward Origin Access Control (OAC) instead of OAI for a while now. OAC signs requests to S3 with SigV4 instead of relying on a canonical-user identity, and it’s the direction CloudFront is actually going. Swapping this in sounds cosmetic. It isn’t.

The origin block goes from:

hcl

s3_origin_config {
  origin_access_identity = aws_cloudfront_origin_access_identity.oai.cloudfront_access_identity_path
}

to:

hcl

origin_access_control_id = aws_cloudfront_origin_access_control.website_oac.id

But the bucket policy’s Principal has to change too from the OAI's canonical user to the CloudFront service principal, scoped down with a Condition on AWS:SourceArn so it only trusts your distribution:

hcl

Principal = { Service = "cloudfront.amazonaws.com" }
Condition = {
  StringEquals = {
    "AWS:SourceArn" = aws_cloudfront_distribution.cloudfront_distribution.arn
  }
}

Run terraform plan after this change and don't skim it swapping the origin type forces a replace on the bucket policy and can force distribution changes too, depending on your provider version. If this were already live for real traffic, that's the kind of plan you read line by line before typing yes.

A hardcoded bucket name will bite the next person (or future you)

The original variables.tf had a default like bucket_name = "****-bucket-505". Fine for me, useless for anyone else S3 bucket names are globally unique across every AWS account on the planet, not just yours. If you're publishing infrastructure code for others to actually run (which, if you're writing it up on Medium, you probably are), drop the default entirely:

hcl

variable "bucket_name" {
  description = "Name of the S3 bucket to host the website. Must be globally unique."
  type        = string
}

No default means Terraform makes the next person choose their own name instead of silently colliding with mine.

Uploading files one resource at a time doesn’t scale

The original config had two separate aws_s3_object resources one for index.html, one for error.html. Add a third file to the site and you're editing main.tf again. That's not a workflow, that's a chore.

The fix is a for_each over the actual directory:

hcl

resource "aws_s3_object" "website_files" {
  for_each = fileset("website/", "**")

bucket = aws_s3_bucket.website_bucket.id
  key    = each.value
  source = "website/${each.value}"
  etag   = filemd5("website/${each.value}")

content_type = lookup(
    { html = "text/html", css = "text/css", js = "application/javascript" },
    lower(element(split(".", each.value), length(split(".", each.value)) - 1)),
    "application/octet-stream"
  )
}

Drop a file into website/, run apply, done. The content_type lookup matters too S3 doesn't guess MIME types for you, and a .html file served as application/octet-stream means your browser downloads it instead of rendering it.

The local-exec provisioner that broke on Windows

I wanted cache invalidation to happen automatically a null_resource that hashed the website/ directory and ran aws cloudfront create-invalidation whenever content changed. Clean idea. It broke immediately:

Error running command 'aws cloudfront create-invalidation --distribution-id ... --paths "/*"': exit status 254.
Error: An error occurred (InvalidArgument) ... invalid invalidation paths.

The root cause had nothing to do with CloudFront or the AWS CLI itself. local-exec runs through your OS's default shell cmd.exe on Windows and cmd.exe doesn't strip embedded double quotes the way bash does. The AWS CLI was literally receiving the four-character string "/*", quote marks included, instead of /*. CloudFront correctly rejected garbage input.

The real lesson here isn’t “use PowerShell as your interpreter” (you can, and it fixes it). It’s that provisioners that shell out are inherently host-dependent, and that dependency is invisible until someone runs your code on a different OS than you tested on. I ended up ripping it out entirely and documenting the manual invalidation command in the README instead one less moving part, one less thing that behaves differently depending on who’s running it.

403, not 404 S3’s error codes will surprise you

I added a custom_error_response block so a missing page would route to a friendly error.html instead of raw XML:

hcl

custom_error_response {
  error_code         = 404
  response_code      = 404
  response_page_path = "/error.html"
}

This alone doesn’t work reliably. When your bucket policy doesn’t grant s3:ListBucket (mine doesn't no reason to), S3 returns 403 Forbidden for a missing object, not 404. CloudFront only maps the error code you tell it to map. Without a matching 403 rule, most real "page not found" cases sail straight past your nice error page:

hcl

custom_error_response {
  error_code         = 403
  response_code      = 404
  response_page_path = "/error.html"
}

Small detail, easy to miss, and the kind of thing you only discover by actually testing a broken link instead of trusting the happy path.

The dumbest bug of the whole project

After all that infrastructure work, my actual error page displayed literal backtick fences (```html) right there on the live site, embedded in the rendered HTML. Not a Terraform problem, not an AWS problem. I'd copy-pasted the file with Markdown code fence syntax still wrapped around it, and it went straight into the repo as-is. The takeaway: infrastructure can be flawless and you'll still ship a typo straight to production if nothing's checking your actual content.

And even after fixing the file and redeploying, the site kept showing the old broken version for a while because CloudFront was still serving a cached copy from before the fix, and I hadn’t invalidated it. A perfectly correct deploy can still look broken to a visitor for up to your cache’s TTL if you don’t force the refresh.

What I’d tell someone starting this from scratch

• Default to OAC over OAI for anything new : OAI still works but you’re building on a path AWS is walking away from.
• Never ship a default value for anything that needs global uniqueness.
• Loop over your content directory instead of hand-writing a resource per file it’s not extra credit, it’s the difference between a config you can actually maintain and one you’ll dread touching in six months.
• Be suspicious of any provisioner that shells out it works on your machine is not a deployment strategy.
• Test your actual 404 path, not just the happy path. S3 and CloudFront’s error codes don’t always match your intuition.
• Cache is a liar. If a fix doesn’t seem to be working, check whether you’re actually looking at the fix or a cached copy of the old version.

None of these are exotic lessons. They’re the ordinary friction of shipping something for real instead of for a tutorial which, honestly, is where most of the actual learning in DevOps work happens.

A honest walkthrough of how I structured, broke, fixed, and shipped a modular Terraform EKS project from scratch

I had been working with Terraform for a while, but everything was going into one big main.tf. It worked until it didn't. Resources were tangled together, debugging was a nightmare, and the moment I wanted to reuse anything I was copying and pasting blocks of code. I decided to rebuild my EKS project properly, breaking it into modules and doing things the right way.

This article is a walkthrough of that journey — the architecture decisions, the code I wrote, the errors I hit, and what I learned. I’m not going to tell you to clone anything. The goal is for you to understand the approach well enough to build your own.

Why Modules?

Before anything else, I want to explain the shift in thinking that made this project click.

In Terraform, a module is just a folder with .tf files. The root module is your top-level directory. Child modules are folders you call from root. Think of them like functions you define the logic once, pass in inputs, and get outputs back. No resource duplication, no spaghetti references.

The project ended up with this structure:

root/
├── main.tf              # Wires all modules together
├── variables.tf         # Root-level variable declarations
├── outputs.tf           # Exposes key values after apply
├── terraform.tfvars     # Your real values (gitignored)
├── terraform.tfvars.example  # Dummy values (committed)
└── modules/
    ├── state/           # S3 bucket + DynamoDB for remote state
    ├── vpc/             # VPC, subnets, IGW, route tables, SG
    ├── iam/             # IAM roles, EKS cluster, node group
    └── ec2/             # Bastion EC2 instance

Four modules, each owning a distinct layer. The state module lays the foundation. The VPC module builds the network. The IAM module provisions the EKS cluster and its roles. The EC2 module drops a bastion instance into the network.

The Golden Rule That Took Me a While to Internalize

Modules cannot see each other’s resources directly.

If the IAM module needs subnet IDs that were created by the VPC module, it cannot reference aws_subnet.my_tf_subnet_1.id directly. Those subnets don't exist inside the IAM module, they live in the VPC module. The only way to pass values between modules is:

1. The VPC module outputs the value
2. The root main.tf catches that output
3. The root passes it as an input variable to the IAM module

I hit this as an error probably five or six times before it fully sank in. Every A managed resource has not been declared in module.X error I got during this project came down to this one rule.

Step 1 — The State Module

The very first thing I built was the state infrastructure. Before any other AWS resources exist, you need somewhere to store the Terraform state file safely.

resource "aws_s3_bucket" "terraform_state" {
  bucket = "ozort-terraform-state-file"
}

resource "aws_s3_bucket_versioning" "enabled" {
  bucket = aws_s3_bucket.terraform_state.id
  versioning_configuration {
    status = "Enabled"
  }
}

resource "aws_s3_bucket_server_side_encryption_configuration" "default" {
  bucket = aws_s3_bucket.terraform_state.id
  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm = "AES256"
    }
  }
}

resource "aws_s3_bucket_public_access_block" "public_access" {
  bucket                  = aws_s3_bucket.terraform_state.id
  block_public_acls       = true
  block_public_policy     = true
  ignore_public_acls      = true
  restrict_public_buckets = true
}

resource "aws_dynamodb_table" "terraform_locks" {
  name         = "terraform-up-and-running-locks"
  billing_mode = "PAY_PER_REQUEST"
  hash_key     = "LockID"

  attribute {
    name = "LockID"
    type = "S"
  }
}

The S3 bucket stores the state file with versioning enabled so if something goes wrong you can roll back to a previous state. AES256 encryption and public access blocking are non-negotiable. The DynamoDB table handles state locking, preventing two simultaneous terraform apply runs from corrupting the state.

The chicken-and-egg problem: You can’t configure Terraform to use an S3 backend before the S3 bucket exists. So the correct order is — apply the state module first to create the bucket and table, then add the backend configuration and run terraform init again to migrate state into S3:

terraform {
  backend "s3" {
    bucket         = "ozort-terraform-state-file"
    key            = "terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-up-and-running-locks"
    encrypt        = true
  }
}

Step 2 — The VPC Module

The VPC module owns all the networking. One VPC, two public subnets across two availability zones, an Internet Gateway, a route table, and a security group.

resource "aws_vpc" "my_tf_vpc" {
  cidr_block = var.vpc-cidr
}

resource "aws_subnet" "my_tf_subnet_1" {
  vpc_id                  = aws_vpc.my_tf_vpc.id
  cidr_block              = var.subnet1-cidr
  map_public_ip_on_launch = true
  availability_zone       = var.subnet1-az

  tags = {
    Name = "my_tf_subnet_1"
  }
}

resource "aws_subnet" "my_tf_subnet_2" {
  vpc_id                  = aws_vpc.my_tf_vpc.id
  cidr_block              = var.subnet2-cidr
  map_public_ip_on_launch = true
  availability_zone       = var.subnet2-az

  tags = {
    Name = "my_tf_subnet_2"
  }
}

resource "aws_internet_gateway" "my_tf_igw" {
  vpc_id = aws_vpc.my_tf_vpc.id
}

resource "aws_route_table" "my_tf_rt" {
  vpc_id = aws_vpc.my_tf_vpc.id

  route {
    cidr_block = "0.0.0.0/0"
    gateway_id = aws_internet_gateway.my_tf_igw.id
  }
}

resource "aws_route_table_association" "my_tf_rt_association_1" {
  subnet_id      = aws_subnet.my_tf_subnet_1.id
  route_table_id = aws_route_table.my_tf_rt.id
}

resource "aws_route_table_association" "my_tf_rt_association_2" {
  subnet_id      = aws_subnet.my_tf_subnet_2.id
  route_table_id = aws_route_table.my_tf_rt.id
}

Two subnets across two AZs is not optional for EKS the control plane requires multi-AZ placement. I learned that the hard way.

The security group uses the newer aws_vpc_security_group_ingress_rule and aws_vpc_security_group_egress_rule resource types rather than inline rules, which gives you more granular control:

resource "aws_security_group" "my_tf_vpc_sg" {
  name   = "my_tf_vpc_sg"
  vpc_id = aws_vpc.my_tf_vpc.id
}

resource "aws_vpc_security_group_ingress_rule" "allow_ssh_ipv4" {
  security_group_id = aws_security_group.my_tf_vpc_sg.id
  cidr_ipv4         = "0.0.0.0/0"
  from_port         = 22
  ip_protocol       = "tcp"
  to_port           = 22
}

resource "aws_vpc_security_group_egress_rule" "allow_all_traffic_ipv4" {
  security_group_id = aws_security_group.my_tf_vpc_sg.id
  cidr_ipv4         = "0.0.0.0/0"
  ip_protocol       = "-1"
}

Note: 0.0.0.0/0 on SSH is fine for a learning project but should be locked down to your specific IP in production.

The VPC module exposes four outputs that both the IAM and EC2 modules depend on:

output "vpc_id" {
  value = aws_vpc.my_tf_vpc.id
}

output "subnet_1_id" {
  value = aws_subnet.my_tf_subnet_1.id
}

output "subnet_2_id" {
  value = aws_subnet.my_tf_subnet_2.id
}

output "sg_id" {
  value = aws_security_group.my_tf_vpc_sg.id
}

Step 3 — The IAM Module

This is the heaviest module. It creates two IAM roles, one for the EKS control plane (ed-eks-master) and one for worker nodes (ed-eks-worker) — attaches all required policies, then provisions the EKS cluster and managed node group.

The master role

resource "aws_iam_role" "master" {
  name = "ed-eks-master"

  assume_role_policy = <<POLICY
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "Service": "eks.amazonaws.com" },
      "Action": "sts:AssumeRole"
    }
  ]
}
POLICY
}

resource "aws_iam_role_policy_attachment" "AmazonEKSClusterPolicy" {
  policy_arn = "arn:aws:iam::aws:policy/AmazonEKSClusterPolicy"
  role       = aws_iam_role.master.name
}

resource "aws_iam_role_policy_attachment" "AmazonEKSVPCResourceController" {
  policy_arn = "arn:aws:iam::aws:policy/AmazonEKSVPCResourceController"
  role       = aws_iam_role.master.name
}

The worker role

The worker role is what EC2 nodes use to communicate with the EKS control plane, pull images from ECR, and access other AWS services. I also created a custom autoscaler policy so the cluster can scale its own node group:

resource "aws_iam_policy" "autoscaler" {
  name   = "ed-eks-autoscaler-policy"
  policy = <<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "autoscaling:DescribeAutoScalingGroups",
        "autoscaling:DescribeAutoScalingInstances",
        "autoscaling:SetDesiredCapacity",
        "autoscaling:TerminateInstanceInAutoScalingGroup",
        "ec2:DescribeLaunchTemplateVersions"
      ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}
EOF
}

Policies attached to the worker role: AmazonEKSWorkerNodePolicy, AmazonEKS_CNI_Policy, AmazonEC2ContainerRegistryReadOnly, AmazonSSMManagedInstanceCore, AWSXRayDaemonWriteAccess, AmazonS3ReadOnlyAccess, and the custom autoscaler policy above.

The EKS cluster and node group

resource "aws_eks_cluster" "eks" {
  name     = "ed-eks-01"
  role_arn = aws_iam_role.master.arn

  vpc_config {
    subnet_ids = [var.subnet_1_id, var.subnet_2_id]
  }

  depends_on = [
    aws_iam_role_policy_attachment.AmazonEKSClusterPolicy,
    aws_iam_role_policy_attachment.AmazonEKSVPCResourceController,
  ]
}

resource "aws_eks_node_group" "backend" {
  cluster_name    = aws_eks_cluster.eks.name
  node_group_name = "dev"
  node_role_arn   = aws_iam_role.worker.arn
  subnet_ids      = [var.subnet_1_id, var.subnet_2_id]
  capacity_type   = "ON_DEMAND"
  disk_size       = 20
  instance_types  = ["t3.micro"]

  remote_access {
    ec2_ssh_key               = var.key
    source_security_group_ids = [var.sg_id]
  }

  labels = tomap({ env = "dev" })

  scaling_config {
    desired_size = 2
    max_size     = 3
    min_size     = 1
  }

  update_config {
    max_unavailable = 1
  }
}

Notice subnet_ids = [var.subnet_1_id, var.subnet_2_id] not a direct resource reference. The IAM module has no idea how those subnets were created. It just receives their IDs through variables passed in from root.

Step 4 — The EC2 Module

A simple bastion instance in subnet 1, with a public IP and SSH access:

resource "aws_instance" "my_tf_ec2" {
  ami                         = var.ami
  instance_type               = var.instance-type
  key_name                    = var.key
  associate_public_ip_address = true
  subnet_id                   = var.subnet_1_id
  vpc_security_group_ids      = [var.sg_id]

  tags = {
    Name = "my_tf_ec2"
  }
}

Clean and simple. Everything it needs the AMI, key pair, subnet, and security group comes in as variables.

Wiring It All Together — Root main.tf

The root main.tf is where all four modules get called and their outputs get connected:

module "state" {
  source = "./modules/state"
}

module "vpc" {
  source       = "./modules/vpc"
  vpc-cidr     = var.vpc-cidr
  subnet1-cidr = var.subnet1-cidr
  subnet2-cidr = var.subnet2-cidr
  subnet1-az   = var.subnet1-az
  subnet2-az   = var.subnet2-az
}

module "iam" {
  source      = "./modules/iam"
  subnet_1_id = module.vpc.subnet_1_id
  subnet_2_id = module.vpc.subnet_2_id
  sg_id       = module.vpc.sg_id
  key         = var.key
}

module "ec2" {
  source        = "./modules/ec2"
  ami           = var.ami
  instance-type = var.instance-type
  key           = var.key
  subnet_1_id   = module.vpc.subnet_1_id
  sg_id         = module.vpc.sg_id
}

The root creates no AWS resources directly. It just coordinates calling modules, catching their outputs, and passing them as inputs to other modules. The syntax is always module.module_name.output_name.

Variables and tfvars

The variables.tf file declares what inputs exist, their types, descriptions, and optional defaults:

variable "region" {
  type        = string
  description = "AWS region to deploy resources"
  default     = "us-east-1"
}

variable "ami" {
  type        = string
  description = "AMI ID for the EC2 instance"
}

variable "key" {
  type        = string
  description = "Name of the SSH key pair"
}

variable "vpc-cidr" {
  type        = string
  description = "CIDR block for the VPC"
  default     = "10.10.0.0/16"
}

Variables without a default like ami and key must be supplied, usually through terraform.tfvars. But that file never gets committed to git. Instead, a terraform.tfvars.example with dummy values sits in the repo so anyone building something similar knows what to fill in:

ami          = "ami-xxxxxxxxxxxxxxxxx"
key          = "your-key-pair-name"
vpc-cidr     = "10.0.0.0/16"
subnet1-cidr = "10.10.1.0/24"
subnet2-cidr = "10.10.2.0/24"
subnet1-az   = "us-east-1a"
subnet2-az   = "us-east-1b"

The .gitignore blocks the real file from ever being committed:

*.tfvars
*.tfstate
*.tfstate.backup
.terraform/

Outputs

After terraform apply completes, these values get printed:

output "endpoint" {
  value = module.iam.endpoint
}

output "worker_node_sg_id" {
  value = module.vpc.sg_id
}

output "s3_bucket_arn" {
  value       = module.state.s3_bucket_arn
  description = "The ARN of the S3 bucket"
}

output "dynamodb_table_name" {
  value       = module.state.dynamodb_table_name
  description = "The name of the DynamoDB table"
}

Every output goes through its module module.iam.endpoint, module.vpc.sg_id, not aws_eks_cluster.eks.endpoint directly. The root module cannot reach inside a child module's resources.

Mistakes I Made and What They Taught Me

Hyphens in variable names. Terraform does not allow hyphens in variable names, output names, or module argument names. I used subnet-id, sg-id, instance-type throughout the project and hit Unsupported argument errors repeatedly. Underscores everywhere subnet_id, sg_id, instance_type — is the correct convention.

Reaching across module boundaries. Every error that read A managed resource has not been declared in module.X was the same mistake: referencing a resource that lives in a different module. The fix every time was the same: output it from the source module, catch it in root, pass it as a variable to the destination module.

Root outputs referencing resources directly. My outputs.tf originally had lines like value = aws_eks_cluster.eks.endpoint. That resource doesn't exist in the root module, it lives in the IAM module. Every root output must go through module.module_name.output_name.

The import trick. After refactoring from a flat structure into modules, Terraform lost track of resources it had already created. Rather than destroying and recreating everything, I used terraform import to reconnect existing AWS resources to the new module paths in state:

terraform import module.state.aws_s3_bucket.terraform_state ozort-terraform-state-file
terraform import module.state.aws_dynamodb_table.terraform_locks terraform-up-and-running-locks

This is one of the most useful commands in Terraform and one of the least talked about.

What’s Next

This project gave me a working modular EKS cluster with remote state and proper module separation. The natural next steps are:

• Add private subnets and a NAT gateway for production-grade networking
• Lock down the SSH security group rule from 0.0.0.0/0 to a specific IP
• Configure a Kubernetes provider to deploy workloads onto the cluster
• Set up a CI/CD pipeline with GitHub Actions to run terraform plan on every pull request
• Add tagging conventions across all resources for cost tracking

Final Thoughts

The shift from a flat Terraform file to a proper modular structure is not just aesthetic. It forces clean separation of concerns, makes individual layers testable in isolation, and makes the infrastructure readable to anyone who picks it up. The errors along the way the module boundary violations, the hyphen naming issues, the state import were each a lesson that wouldn’t have come from just reading the docs.

Build it, break it, fix it. That’s how it sticks.

Written by Abu Bobby — DevOps & Cloud Engineering practitioner.

Infrastructure as Code (IaC) is one of the most valuable skills in modern cloud engineering and one of the best ways to practice it is by building something simple but practical.

In this guide, I’ll walk through how to create and host a static website on AWS S3 using Terraform. This project is perfect for beginners looking to solidify their Terraform knowledge while building something tangible.

Why Use Terraform Instead of the AWS Console?

You could create an S3 bucket manually via the AWS Console but that approach doesn’t scale well.

Terraform allows you to:

• Automate infrastructure deployment
• Maintain consistency across environments
• Reduce human error
• Version-control your infrastructure

In short: faster, safer, and more reliable deployments.

Prerequisites

Before you begin, make sure you have:

• An AWS account
• Terraform CLI installed
• Basic understanding of Terraform concepts (providers, resources, variables)

What We’ll Build

By the end of this tutorial, you’ll have:

• An S3 bucket provisioned with Terraform
• Static website hosting enabled
• Website files uploaded automatically
• Public access configured
• A live website endpoint

Step 1: Set Up Your Project Directory

Create a working folder and navigate into it:

mkdir terraform-s3-web
cd terraform-s3-web

Step 2: Configure the AWS Provider

Create a file called provider.tf and define your AWS provider.

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "6.42.0"
    }
  }
}

provider "aws" {
  # Configuration options
  region = "Your_Specified_region"
}

Then initialize Terraform:

terraform init

This downloads the required provider plugins and prepares your environment.

Step 3: Define Variables

Create a variables.tf file:

variable "bucket_name" {
  description = "Unique name for the S3 bucket"
  type        = string
}

Tip: S3 bucket names must be globally unique.

Step 4: Create the S3 Bucket

Create a main.tf, define your bucket:

resource "aws_s3_bucket" "website_bucket" {
  bucket = var.bucket_name
}

Step 5: Configure Bucket Ownership

Ensure all objects are owned by the bucket owner:

resource "aws_s3_bucket_ownership_controls" "ownership" {
  bucket = aws_s3_bucket.website_bucket.id

  rule {
    object_ownership = "BucketOwnerPreferred"
  }
}

Step 6: Enable Public Access

By default, S3 blocks public access. We need to override that:

resource "aws_s3_bucket_public_access_block" "public_access" {
  bucket = aws_s3_bucket.website_bucket.id

  block_public_acls       = false
  block_public_policy     = false
  ignore_public_acls      = false
  restrict_public_buckets = false
}

Step 7: Set Bucket ACL

Allow public read access:

resource "aws_s3_bucket_acl" "acl" {
  depends_on = [aws_s3_bucket_ownership_controls.ownership]

  bucket = aws_s3_bucket.website_bucket.id
  acl    = "public-read"
}

Step 8: Upload Website Files

Upload your static files (e.g., index.html, error.html, images):

resource "aws_s3_object" "index" {
  bucket = aws_s3_bucket.website_bucket.id
  key    = "index.html"
  source = "index.html"
  acl    = "public-read"
}

Repeat this block for each file you want to upload.

Step 9: Enable Static Website Hosting

Configure your bucket for website hosting:

resource "aws_s3_bucket_website_configuration" "website" {
  depends_on = [aws_s3_object.index]

  bucket = aws_s3_bucket.website_bucket.id

  index_document {
    suffix = "index.html"
  }

  error_document {
    key = "error.html"
  }
depends_on = [ aws_s3_bucket_acl.example ]
}

The depends_on argument makes sure the s3 bucket is created first before the other processes are started.

Step 10: Deploy Your Infrastructure

Run:

terraform plan
terraform apply

Terraform will show you what it plans to create before applying the changes.

Step 11: Test Your Website

After deployment:

1. Go to your AWS S3 Console
2. Open your bucket
3. Navigate to the Properties tab
4. Scroll to the Static Website Hosting section
5. Click the endpoint URL

🎉 Your website should now be live!

Deploying frontend apps doesn’t have to be scary or complicated. In this article, we’ll walk through how to deploy a React app built with Vite to an AWS EC2 instance, using GitHub Actions to automate the entire process.

By the end, every push to main will automatically build and deploy your app to your server. No manual uploads. No stress.

What We’ll Build

We’ll set up a simple but real-world CI/CD pipeline that does the following:

1. Create a React app using Vite
2. Push the code to GitHub
3. Create an EC2 instance on AWS
4. Configure a self-hosted GitHub Actions runner on EC2
5. Set up a GitHub Actions workflow to deploy the app

Step 1: Create a React App with Vite.

Install Node.js

Vite requires Node.js version 18 or higher.

Check if Node.js is installed:

node -v
npm -v

If not installed, download the LTS version from nodejs.org and install it.

Create a New Vite + React Project

Run the command below in your terminal:

npm create vite@latest <your-app-name>

When prompted:

• Project name → my-react-app (or any name you like)
• Framework → React
• Variant → JavaScript

Install Dependencies

Move into the project directory and install dependencies:

cd my-react-app
npm install

Run the App Locally

Start the development server:

npm run dev

Open the displayed URL (usually http://localhost:5173) in your browser.
You should see the default React + Vite page 🎉

Build for Production

When you’re ready to deploy:

npm run build

This creates a dist/ folder containing optimized static files.
These are the files we’ll serve with nginx on our EC2 instance.

Push the Code to GitHub

Initialize Git, commit, and push your code to a GitHub repository:

git init
git add .
git commit -m "Initial commit - React app with Vite"
git branch -M main
git remote add origin https://github.com/your-username/my-react-app.git
git push -u origin main

Step 2: Create an EC2 Instance on AWS

Log in to the Amazon Web Services Management Console and navigate to EC2 → Launch Instance.

Use the Following Configuration

• Name: react-cicd
• AMI: Ubuntu
• Instance type: t3.micro (Free Tier)
• Key pair: Create a new one and download the .pem file
• Tick both allow HTTP/HTTPS tick boxes like on the image below:

• Launch the instance.

SSH into the Server

From the EC2 dashboard:

1. Select your instance
2. Click Connect → SSH Client
3. Follow the instructions provided by AWS
4. you’re looking for 2 commands that look like the ones below.

Remember your terminal should be in the directory where you kept your key file! Never share this file with anyone!

Make your key file secure:

chmod 400 your-key.pem

Connect to the instance:

ssh -i your-key.pem ubuntu@your-ec2-public-dns

Install Updates and Nginx

Once connected:

sudo apt-get update
sudo apt-get install nginx -y

Nginx will serve our React production build.

Step 3: Set Up a Self-Hosted GitHub Actions Runner

Instead of using GitHub’s hosted runners, we’ll run jobs directly on our EC2 instance.

In your GitHub repository:

1. Go to Settings → Actions → Runners
2. Click New self-hosted runner
3. Select Linux (x64)

Follow the commands shown inside your EC2 SSH session.
When you reach ./run.sh, do not run it.

Instead, install the runner as a service:

sudo ./svc.sh install
sudo ./svc.sh start

Refresh the GitHub page until the runner shows as Idle.

Step 4: Create the GitHub Actions Workflow

In your repository, go to the Actions tab, search for a Node workflow and select configure.

This creates a file at:

.github/workflows/node.js.yml

Replace its contents with:

name: Node.js CI

on:
  push:
    branches: [ "main" ]

jobs:
  build:

    runs-on: self-hosted

    strategy:
      matrix:
        node-version: [20.x]

    steps:
    - uses: actions/checkout@v3
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v3
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
    - run: npm ci
    - run: npm run build --if-present
    - name: Clear contents of /var/www/html
      run: sudo rm -rf /var/www/html/*
    - name: Copy dist folder to /var/www/html
      run: sudo cp -r dist/* /var/www/html

Commit the workflow file. This will immediately trigger the pipeline.

Step 5: View Your Deployed App 🎉

Go to your EC2 instance details and copy the Public IPv4 DNS.

Important:
Remove the s from https.

Example:

http://ec2-35-177-1xx-238.eu-west-2.compute.amazonaws.com

Or simply use the public IP address of your EC2 instance.

http://xx.xxx.xx.xx

Your React app should now be live and served by nginx.

Final Thoughts

You’ve just built a full CI/CD pipeline using:

• GitHub for version control
• GitHub Actions for automation
• Amazon EC2 for hosting

Every push to main now automatically builds and deploys your app just like a real production workflow.

Deploying a React App to EC2 Using GitHub Actions was originally published in DevOps.dev on Medium, where people are continuing the conversation by highlighting and responding to this story.

If you’re learning DevOps or cloud engineering, setting up a real CI/CD pipeline is one of the best ways to move from theory to practice. In this article, I’ll walk you through how to deploy a simple Node.js application to an AWS EC2 instance using GitHub Actions with a self‑hosted runner.

By the end of this guide, you’ll have:

• A Node.js app running on an EC2 instance
• Automated tests running on every push
• Automatic deployment triggered by GitHub Actions

This project is beginner‑friendly but also mirrors real‑world CI/CD workflows.

What We’ll Build

Here’s what the overall flow looks like:

1. Create a simple Node.js application
2. Push the code to GitHub
3. Create EC2 instance on AWS
4. Set up a self‑hosted GitHub Actions runner on EC2
5. Configure a CI/CD workflow
6. Automatically test and deploy the app on every push

Step 1: Create a Simple Node.js Application

Start by creating a new project directory and initializing a Node.js app:

mkdir cicd-app
cd cicd-app
npm init -y

Next, install the required dependencies:

npm install express jest supertest

Project Structure

Create the following folders and files:

mkdir src
mkdir src/public
touch src/index.js src/app.js src/app.test.js
touch src/public/index.html
touch .gitignore

Step 2: Application Code

src/index.js

This file starts the server:

const app = require("./app");
const port = process.env.PORT || 3000;

app.listen(port, () => console.log("Server listening on port 3000!"));

src/app.js

This defines the Express app and routes:

const express = require("express");
const path = require("path");
const app = express();
app.use(express.static("public"));

app.get("/test", (_req, res) => {
  res.status(200).send("Hello world");
});

app.get("/", (req, res) => {
  res.sendFile(path.join(__dirname, "public", "index.html"));
});

module.exports = app;

src/app.test.js

A simple test to validate our API endpoint:

const app = require("./app");
const supertest = require("supertest");
const request = supertest(app);

describe("/test endpoint", () => {
  it("should return a response", async () => {
    const response = await request.get("/test");
    expect(response.status).toBe(200);
    expect(response.text).toBe("Hello world");
  });
});

src/public/index.html

A basic html page to confirm deployment:

<!DOCTYPE html>
<html>
  <head>
    <title>Demo Application Node Web Server</title>
    <style>
      h1 {
        text-align: center;
        margin-right: 5px;
      }
      body {
        color: #bcbcce;
        background-color: #151617;
        display: flex;
        justify-content: center;
        align-items: center;
        height: 100vh;
        margin: 0;
      }
    </style>
  </head>
  <body>
    <h1>Products Page</h1>
    <p>version 1.0</p>
  </body>
</html>

Step 3: Configure package.json

Update your package.json scripts so we can easily run and test the app:

"scripts": {
    "start": "node src",
    "test": "jest src/app.test.js"
  },

You can now:

• Start the app with npm start
• Run tests with npm run test

Add node_modules to .gitignore:

node_modules/

Push the project to a new GitHub repository.

Step 4: Create an EC2 Instance

1. Log in to the AWS Management Console
2. Go to EC2 → Launch Instance
3. Use the following configuration:

• Name: node-cicd-app
• AMI: Ubuntu
• Instance Type: t3.micro (Free Tier)
• Key Pair: Create a new one (save the .pem file)

4. Launch the instance.

Step 5: Configure Security Group

1. Select the newly created instance.
2. In the tabs below, click Security.
3. Then click on the Security groups link associated with the instance.
4. In the Inbound rules tab of the security group, click on Edit inbound rules.
5. Edit the instance’s inbound rules to allow:

• SSH (22) from your IP
• HTTP (80) from anywhere
• Custom TCP (3000) from anywhere

This allows browser access to the Node.js app.

Step 6: Create a GitHub Actions Workflow

In your GitHub repository:

1. Go to Actions
2. Search for a Node.js workflow
3. Click Configure

Replace the generated YAML file with:

name: Node.js CI/CD

on:
  push:
    branches: [ "main" ]

jobs:
  build:
    runs-on: self-hosted
    strategy:
      matrix:
        node-version: [18.x]
        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
    steps:
    - uses: actions/checkout@v3
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v3
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
    - run: npm ci
    - run: npm test
    - run: pm2 restart backendserver

At this point, the workflow will fail because the self‑hosted runner hasn’t been configured yet.

Step 7: Connect to EC2 via SSH

From your local terminal:

1. Navigate to the directory containing your .pem file
2. Set permissions:

chmod 400 cicd-key.pem

3. Connect to the instance:

 ssh -i cicd-key.pem ubuntu@<EC2_PUBLIC_IP>

To find the exact commands for your EC2 instance:

1. Head to AWS Management Console and open the newly created instance. Click on the Connect button.
2. Navigate to SSH Client. You’d find the first and second command specific to your EC2 instance and you can just copy and paste them in your terminal.

Step 8: Set Up a Self‑Hosted GitHub Actions Runner

In your GitHub repository:

• Go to Settings → Actions → Runners
• Click New self-hosted runner
• Select Linux (x64)

Follow the displayed commands inside your EC2 SSH session.

After running the ./run.sh command, a “Connected to GitHub” message confirms success.

Once installed, start the runner service:

sudo ./svc.sh install
sudo ./svc.sh start

Step 9: Install Node.js and PM2 on EC2

Update the system and install Node.js:

sudo apt update
curl -sL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

Install PM2:

sudo npm install -g pm2

Step 10: Start the Application

Navigate to the project directory created by the runner:

cd ~/actions-runner/_work/cicd-app/cicd-app

Start the app with PM2:

pm2 start src/index.js --name=backendserver

The app now runs in the background and survives SSH disconnects.

Step 11: Verify Deployment

Open your browser and visit:

http://<EC2_PUBLIC_IP>:3000

You should see the Products Page — version 1.0.

Step 12: Test the CI/CD Pipeline

Make a small change to index.html and push it to GitHub.

Once the push is detected:

• GitHub Actions runs tests
• The app is automatically restarted on EC2

🎉 You’ve successfully built a CI/CD pipeline with Node.js, GitHub Actions, and AWS EC2.

Final Thoughts

This project demonstrates a real‑world CI/CD setup using a self‑hosted runner. It’s a great foundation for exploring more advanced topics like load balancing, environment variables, secrets management, and containerization.

If you’re learning DevOps, this is a solid project to showcase in your portfolio.

In this article, I’ll walk you through:

• My initial AWS CI/CD setup
• The issues that blocked me
• How I successfully switched to GitHub Actions
• And how you can deploy a static site to EC2 using Nginx + GitHub Actions

This is a real-world walkthrough — mistakes, fixes, and all.

Pre-Requisites

Before kicking off this project there are some things that are quite important to have:

• A GitHub repository containing your static website (index.html)
• An AWS account with an IAM user with the necessary permissions to access CodeBuild, CodeDeploy, S3, and EC2
• An EC2 Ubuntu instance
• Basic familiarity with: AWS services, Linux commands, and GitHub.

Initial Approach: AWS CI/CD (CodeBuild & CodeDeploy)

My first approach was to use AWS CI/CD services to build and deploy my static website. To do this, two configuration files are required in your repository:

1️⃣ appspec.yaml (For CodeDeploy)

This file defines how CodeDeploy installs and runs your application on EC2. It contains lifecycle hooks like BeforeInstall and AfterInstall, which are typically used to install and start Nginx.
Configure with this:

version: 0.0
os: linux
files:
  - source: /
    destination: /var/www/html
hooks:
  AfterInstall:
    - location: scripts/install_nginx.sh
      timeout: 300
      runas: root
  ApplicationStart:
    - location: scripts/start_nginx.sh
      timeout: 300
      runas: root

2️⃣ buildspec.yml (For CodeBuild)

This file defines build instructions for CodeBuild and is divided into phases:

• Install — Install Nginx
• Build — Move index.html to /var/www/html
• Post-build — Upload artifacts to an S3 bucket

Configure with this:

version: 0.2

phases:
  install:
    commands:
      - echo Installing NGINX
      - sudo apt-get update
      - sudo apt-get install nginx -y
  build:
    commands:
      - echo Build started on `date`
      - cp index.html /var/www/html/
  post_build:
    commands:
      - echo Configuring NGINX

artifacts:
  files:
    - '**/*'

Create additional scripts folder

Inside your repo, You’d need additional scripts. These scripts are there to tell the server what to do during deployment.

create a scripts/folder:

Then these add two files inside it.
scripts/install_nginx.sh

#!/bin/bash
apt update -y
apt install nginx -y

scripts/start_nginx.sh

#!/bin/bash
systemctl start nginx
systemctl enable nginx

When You’re done your repo should look like this:

Step1: Create an S3 Bucket for Build Artifacts

So, the first step is to create an S3 bucket to store build artifacts:
1. Head over to the AWS S3 console
2. Click Create bucket
3. Enter a unique name (e.g. ozort-demo)
4. Leave all other settings as default
5. Click Create Bucket.

Step 2: Configure AWS CodeBuild

1. Open the CodeBuild service from the AWS Console.
2. Click Create Build Project.

Project Settings

• Project name: nginx-build
• Project Type: Default
• Source provider: GitHub
• Repository: Public repository
• Repository URL: Your GitHub repo link

Environment

• Operating system: Ubuntu
• Leave other settings as default

Buildspec

• Choose Use a buildspec file (this will use the buildspec.yml from your repository).

Artifacts

• Type: Amazon S3
• Bucket: Your S3 bucket
• Name: demo-nginx
• Packaging: Select Zip as the preferred Artifacts packing method.
• Leave everything else as default

Click Create build project, then Start build (it usually takes around 4–5 minutes). Once done, your project will be successfully built and your artifacts will be stored in the S3 bucket!

Setting Up EC2 Instance and IAM Roles for Deployment

Once the build artifacts were ready, I moved on to deployment.
This required:

• IAM roles
• An EC2 instance
• CodeDeploy agent installation

Step 3: Create IAM Roles

We’ll need just two roles, one for EC2 and another for CodeDeploy.

Role 1: IAM Role for EC2
1. navigate to the IAM Console and click on Roles in the sidebar.
2. Click Create Role
3. Choose AWS Service, and select EC2 under the use case.
4. Click Next, and attach the following policies:

• AmazonEC2FullAccess
• AmazonEC2RoleforAWSCodeDeploy
• AmazonEC2RoleforAWSCodeDeployLimited
• AWSCodeDeployRole
• AmazonS3FullAccess
• AWSCodeDeployFullAccess

5. Click Next, Name the role: ec2-code-deploy, and Create Role.

Role 2: IAM Role for CodeDeploy (Issue Encountered)

Due to a recent AWS update, I could no longer select CodeDeploy directly as a use case on a free AWS account.

Workaround:
Select EC2 as the use case and manually attach:

• AWSCodeDeployRole
• AmazonS3FullAccess
• AmazonEC2FullAccess

6. Name the role: ec2-code-deploy-role and create it.

This worked, but it foreshadowed the bigger issue ahead.

Step 4: Launch EC2 and Install CodeDeploy Agent

Now we need to launch and setup our EC2 Instance that will serve our static website.
1. Navigate to the EC2 Console, click Launch Instance
2. Instance name: nginx-demo

EC2 Configuration

• AMI: Ubuntu (latest)
• Instance type: t3.micro
• Security group: Allow HTTP (port 80) and HTTPS access
• Key Pair: No need to create (we’ll use EC2 Connect)
• Launch the instance

Install CodeDeploy Agent
Once your instanced is running. (You should be able to see this on the EC2 instance page)
1. Select the instance and click Connect
2. Choose EC2 Instance Connect and open the terminal
3. Run the following commands:

sudo apt update`
sudo apt install ruby-full -y
sudo apt install wget -y
cd /home/ubuntu
wget https://aws-codedeploy-us-east-1.s3.us-east-1.amazonaws.com/latest/install # Change Region Accordingly
chmod +x ./install
sudo ./install auto
sudo systemctl status codedeploy-agent

⚠️ If you’re using a region other than us-east-1 (N. Virginia), change the wget URL to match your region.

After installation, you should see that the CodeDeploy agent is active and running.

Step 5: Attach IAM Role to EC2 Instance

To allow your EC2 instance to access S3 and CodeDeploy, we need to attach the ec2-code-deploy role:
1. Go back to the EC2 Console
2. Select the nginx-demo instance
3. Click Actions → Security → Modify IAM Role
4. Choose ec2-code-deploy and click Update IAM Role

The Blocker: CodeDeploy Isn’t Available

At this point, I attempted to create a CodeDeploy application and discovered that CodeDeploy is no longer available on free AWS accounts.
This completely stopped the pipeline.

Pivot: Switching to GitHub Actions 🚀

After speaking with a mentor, I switched to GitHub Actions, which turned out to be:

• Easier to configure
• Free
• More flexible

Switching to GitHub Actions

Switching to GitHub Actions will require the following steps
· Preparing your EC2 server
· Creating a deploy folder on EC2
· Adding SSH Key to GitHub Secrets
· Adding GitHub Actions to Workflow

Step 1: Prepare the EC2 Server

Install and start Nginx:

sudo apt update
sudo apt install nginx -y
sudo systemctl enable nginx
sudo systemctl start nginx

Test in browser:

http://your-ec2-Public-ip

⚠️ Use http:// — not https:// — when accessing the EC2 IP.

You should see Nginx welcome page.

When I did this test, I got a “This site can’t be reached” message and there are a lot of things that could cause this.

Now let’s get into it.
First you need to test if your server is connected to the internet.

Ping google.com

#Ctrl C to Stop

You should see the total number of packets transmitted and received. If its connected it should transmit and receive the same number of times.

Second test would be to check if nginx is active and running

Sudo systemctl status nginx

It should show active (running) if there are no issues.

Third test would be to load the welcome page from inside the terminal

curl http://localhost

If nothing is wrong you should get the welcome page in raw html form.

The last test would be the network test because sometimes AWS blocks inbound web traffic by default. It’s the firewall and it’s a common problem.
Fix it like this:
1. In EC2 → Instances
2. Click your instance
3. Scroll down to Security tab
4. Click the Security group link
5. Click Edit inbound rules
6. Click Add rule

You will be adding 2 rules:

• Allow HTTP (80) from 0.0.0.0/0
• Allow ALL TCP (0–65535) from 0.0.0.0/0

7. Click Save rule

8. Open your EC2 Public ip on your web browser and it should show the nginx welcome page.

⚠️ Use http:// — not https:// — when accessing the EC2 IP.

you should have something like this:

http://52.207.xxx.xx

Step 2: Create Deployment Directory on EC2

On your EC2 terminal:

 sudo mkdir -p /var/www/html
 sudo chown -R ubuntu:ubuntu /var/www/html

Now EC2 is ready to receive files.

Step 3: Configure SSH for GitHub Actions

Generate SSH keys on EC2:

 ssh-keygen -t ed25519 -f github-actions-ec2

You’ll get:

• github-actions-ec2(private key)
• github-actions-ec2.pub(public key)

Add public key to EC2:

cat github-actions-ec2.pub >> ~/.ssh/authorized_keys

Step 4: Add GitHub Secrets

In your GitHub repo:
Settings → Secrets and variables → Actions → New repository secret
Add:

• EC2_HOST → EC2 public IP
• EC2_USER → ubuntu
• EC2_SSH_KEY → Private SSH key contents

⚠️ Paste the entire private key including:

 — — -BEGIN OPENSSH PRIVATE KEY — — -
…
 — — -END OPENSSH PRIVATE KEY — — -

Step 5: Create GitHub Actions Workflow

In your repo create this file:

.github/workflows/deploy.yml

Paste this inside:

name: Deploy Static Site to EC2

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Deploy to EC2 via SSH
      uses: appleboy/scp-action@v0.1.7
      with:
        host: ${{ secrets.EC2_HOST }}
        username: ${{ secrets.EC2_USER }}
        key: ${{ secrets.EC2_SSH_KEY }}
        source: "index.html"
        target: "/var/www/html/"

Final Result 🎉

Push to main, and GitHub Actions:

• Runs the workflow
• Deploys your site to EC2
• Replaces the default Nginx page

Refresh your EC2 IP:

http://your-ec2-ip

Your custom HTML page should now appear instead of Nginx default.

Final Thoughts

This project taught me an important lesson:

Always have a fallback plan in DevOps.

GitHub Actions turned out to be a simpler and more reliable solution than AWS CodeDeploy for this use case.
If this helped you:

• Clap 👏
• Drop a comment
• Or share what broke in your setup.

INTRODUCTION

The sample sales dataset is a dataset that contains information about the sales of miniature vehicle toys such as motorcycles, Classic cars, planes, trains, vintage cars, trucks and buses over the course of three years across various countries.

The purpose of this technical report is to identify trends, patterns and anomalies in the given dataset. Identifying these will help further understand the given data and tell its story.

OBSERVATIONS

After carefully observing the dataset, certain things could be noted,

1. Classic cars seem to be the product line with the highest demand and sales overall. In most of the countries its the most ordered product line and in Switzerland its the only product line that is ordered.

2. I observed that the highest overall orders come from the United States (USA) followed by Spain, France and Australia. These regions prove to be strong marketing regions and would behighly profitable for most miniature toy automotive businesses.

3. I also noted that there was an increase in the quantity and sales of each product line in the year 2004 compared to the year 2003 and there was a general decline in the quantity ordered and sold in the year 2005 across all product lines.

CONCLUSION

1. Given the strong performance of the classic cars product line worldwide, it is advisable to increase production, develop innovative designs, and expand marketing efforts into new regions.
2. We should intensify marketing efforts in regions with low sales, considering promotions and discounts to encourage customer engagement.
3. A more detailed research and analysis should be done to study what caused the increase in orders in the year 2004 and what changed in the year 2005that caused the decline.

THANK YOU.

https://hng.tech/internship, https://hng.tech/hire,

https://hng.tech/premium