Creating an automated serverless website using AWS, GitHub and Terraform

I wanted to create a personal website where I could display information about myself and post technical writing surrounding technologies or ideas I am interested in. For me the site had to be serverless, easy to manage posts and have fully automated deployments. The advantage of this is the less time I have to spend building the website or managing servers the more time I can spend on developing my engineering skills and working on other proejcts. This first led me to Hugo. A lightweight static site generator written in Go that allows me to control the site through markdown and a configuration.toml file! On build Hugo will publish an artefact to public/ in the site root directory. This is the contents for the static site and where index.html will be placed.

So now I have a framework. I’ve met some of my requirements outlined in my introduction. I still needed a serverless platform to deploy to. Amazon S3 meets the requirement in this scenario, whilst S3 is traditionally used for object level cloud storage, it also has a static website hosting feature. We can store our artefact produced by Hugo in a bucket and have S3 serve the contents. This works because the contents of this bucket is static web content. Anything that utilizes server-side processing such as PHP or Python would not be compatible with this feature.

For deployments I can use the same platform where I am storing the source code for this website, GitHub. The actions feature can create automations that will run our Hugo build and then push our artefact to S3.

During the deployment I want to deploy or change our infrastructure as well as deploy our artefact. For this I opted for Terraform, a widely popular infrastructure as code tool to manage my resources in AWS via code. This give us the advantage of having the configuration of our entire infrastructure stored in a version control system. Then from this we can execute automations to deploy our configurations programmatically. Also giving us the advantage of rebuilding the entire configuration at any point, iterate on changes faster and take advantage of Terraforms idempotency.


Installing and configuring Hugo

I needed to install Hugo and its dependency Go.

After installing Hugo and configuring my theme by adding several configurations to my config.toml in the root of the site. I am able to write posts in markdown, this is made even easier by running hugo new posts/ Then test the configurations with hugo serve and run the site locally on the default hugo port so when I navigate to I am presented with my site and first post.

First result

As you can see from the minimal setup I have the ability to post content to my site with a nice theme. /posts/blog/frist-ss.png

Building out the infrastructure

As defined in the architechure diagram above, everything in the blue box we are going to be deploying using Terraform.

  • S3 bucket
  • Cloud Front distrobution
  • Route53 DNS records
  • ACM certificate

Getting Started with Terraform

The first task here is to install Terraform. When we have installed Terraform and verified with terraform -version we can continue. To start we will structure the files based on services and resources that are utilized in that file.

├── env.tfvars

You can see here that there are some files that are not represented by AWS services.

  • - Where we will store our state file and provider configurations.
  • - Where we will declare all of our terraform variables with their type constraints and defaults.
  • env.tfvars - Setting the values that correspond to our variables declared in

In our we will need to configure our backend where our state file will be stored. The state file is used as a source of truth between your resources that are deployed and resources declared as a part of your configuration. When we create a resource as a part of our code, terraform will store the configuration for that resource in the state file. In this instance we have already created an S3 bucket in AWS that will host the state file.

terraform {
   backend "s3" {
       bucket = "logancox-blog-terraform"
       region = "eu-west-1"
       key    = "state/main"

To declare variables in terraform we will use a file a good example will be the bucket name where we will host our build. We set the type to string and add a description, I will not add a default here as I know we are passing in a tfvars file and S3 buckets must be globally unique (we will add a prefix when we create the bucket).

variable "blog_bucket_name" {
   description = "Our main blog bucket where contents are served from"
   type        = string

Finally we set the value of the variable in the tfvars file

blog_bucket_name = "logan-cox-blog-artefacts"

Building the S3 Bucket

The place we are going to store our website’s contents is an S3 bucket. So first we will need to create a bucket with a random prefix to ensure it is globally unique. We will define the name and tags we wish to apply to the bucket. The static website feature must also be enabled with an index_document and error_document. Finally attaching a bucket policy that makes our bucket publicly accessible.

resource "random_string" "random" {
   length           = 4
   special          = false
   lower            = true
   upper            = false
   number           = false
resource "aws_s3_bucket" "blog" {
   bucket = "${random_string.random.result}-${var.blog_bucket_name}"
   tags   = var.global_tags
data "aws_iam_policy_document" "blog" {
   statement {
       actions   = ["s3:GetObject"]
       resources = ["${}/*"]
       principals {
       type        = "*"
       identifiers = ["*"]
resource "aws_s3_bucket_policy" "blog" {
   bucket =
   policy =
resource "aws_s3_bucket_website_configuration" "blog" {
   bucket =
   index_document {
       suffix = "index.html"
   error_document {
       key = "404.html"

Working with Certificate Manager

Before we create our CloudFront distribution we need to ensure we can serve our website over HTTPS. For this we will need a custom SSL certificate. This can be requested using the Certificate Manager service, this allows us to provision and manage SSL/TLS certificates to use with AWS services. The caveat with using ACM and CloudFront is that our certificate must belong in the US-EAST-1 region. So how do we provision resources in multiple regions? We add a provider alias to our configuration as shown below and reference that provider in the resource we are creating.

provider "aws" {
   alias = "acm_provider"
   region = "us-east-1"
resource "aws_acm_certificate" "blog" {
   provider          = aws.acm_provider
   domain_name       = var.domain
   validation_method = "DNS"
   tags = var.global_tags
   lifecycle {
       create_before_destroy = true

As you can see in the configuration we have specified the provider argument that allows provisioning of the certificate in the region we set up an alias for. Then we specify the domain name we want to create the SSL/TLS certificate for and our validation method to prove that we do indeed own this domain. This is done via DNS validation, where we will add CNAME records AWS provide to our DNS configuration in Route53 to establish we own the domain we are requesting the certificate for. As long as these records exist AWS ACM is also able to auto renew our certificates. We have added the create before destroy lifecycle rule so terraform will create a new certificate before it destroys the old on ensuring it is always available as it will have a unique certificate ID, multiple can exist at once for the same domain.

Here you can see we are creating the necessary DNS records to validate we own this domain and our validator resource.

resource "aws_route53_record" "dns_validation" {
   for_each = {
       for item in : item.domain_name => {
       name   = item.resource_record_name
       record = item.resource_record_value
       type   = item.resource_record_type
   allow_overwrite = true
   name            =
   records         = [each.value.record]
   ttl             = 60
   type            = each.value.type
   zone_id         = var.dns_zone_id
resource "aws_acm_certificate_validation" "blog" {
   provider                = aws.acm_provider
   certificate_arn         =
   validation_record_fqdns = [for record in aws_route53_record.dns_validation : record.fqdn]

Building out the CloudFront Distribution

Cloudfront is the content delivery network in AWS. This is a set of globally distributed servers that allow us to cache content. This is where we are going to cache our website’s content that is stored in S3. This should give us lower latency than if we were to access the contents directly from S3 using the static website hosting feature, as it will be cached in an AWS edge location and this is what the user will access.

resource "aws_cloudfront_distribution" "blog" {
   origin {
       domain_name =
       origin_id   = "S3-${var.blog_bucket_name}"
       custom_origin_config {
           http_port              = 80
           # Required but not used
           https_port             = 443
           # The origin endpoint HTTP only hence why we are using cloud front to serve traffic over SSL/TLS
           origin_protocol_policy = "http-only"
           # Required but not used
           origin_ssl_protocols   = ["TLSv1"]
   enabled             = true
   is_ipv6_enabled     = true
   default_root_object = "index.html"
   aliases = ["", ""]
   default_cache_behavior {
       allowed_methods  = ["GET", "HEAD"]
       cached_methods   = ["GET", "HEAD"]
       target_origin_id = "S3-${var.blog_bucket_name}"
       forwarded_values {
           query_string = false
           cookies {
               forward = "none"
       viewer_protocol_policy = "redirect-to-https"
       min_ttl                = 0
       default_ttl            = 3600
       max_ttl                = 86400
   price_class = "PriceClass_200"
   restrictions {
       geo_restriction {
       restriction_type = "whitelist"
       locations        = ["US", "CA", "GB", "DE", "FR"]
   tags = var.global_tags
   viewer_certificate {
       cloudfront_default_certificate = false
       acm_certificate_arn            =
       minimum_protocol_version       = "TLSv1"
       ssl_support_method             = "sni-only"

Setting up Route 53

We need a way in which we can point our domain apex to the address of our cloudfront distribution. For this we will use an alias DNS record to forward all of our traffic to our cloudfront endpoint. This means that users will be connecting to cloudfront over HTTPS where the content is cached and not the bucket endpoint (HTTP). If the content does not exist in the cache cloudfront will request it from its origin(S3).

resource "aws_route53_record" "blog" {
   zone_id = var.dns_zone_id
   name    = var.domain
   type    = "A"
   alias {
       name                   =
       zone_id                =
       evaluate_target_health = true

Constructing the build and deployment pipeline

In Github we can use the actions section to build an automated pipeline that will.

  • Configure our build node with the necessary tools
  • Run our terraform actions. Init, lint, plan and apply.
  • Run Hugo build to produce our deployable artefact
  • Remove stale content from S3
  • Copy the artefact to S3

We have a single job that is run, split into multiple steps for each of our actions. We can define our base variables and then run bash commands in each step to build and deploy our site. We have configured this to run on every push and pull request to the main branch.

name: website-build

    branches: [ main ]
    branches: [ main ]
  # Allows us to trigger at any time

    AWS_ACCESS_KEY_ID:  ${{ secrets.AWS_ACCESS_KEY_ID }}
    S3_BUCKET: cnbr-logan-cox-blog-artefacts

    runs-on: ubuntu-latest
      - uses: actions/checkout@v2
          submodules: true  
          fetch-depth: 0   
      - name: Setup Go environment
        uses: actions/setup-go@v3.0.0

      - name: HashiCorp - Setup Terraform
        uses: hashicorp/setup-terraform@v1.2.1
      - name: Setup Hugo
        run: |
          sudo snap install hugo --channel=extended          
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v1
          aws-region: eu-west-1
      - name: Terraform init
        run : |
          make init          

      - name: Terraform validate
        run : |
          make validate          
      - name: Terraform lint
        run : |
          make lint          
      - name: Terraform plan and apply
        run : |
          make plan
          make apply          
      - name: hugo build
        run : |
          cd $SITE_DIRECTORY
          make build          
      - name: push build artifact to S3
        run: |
          cd $SITE_DIRECTORY
          make prune
          make deploy          

Other solutions S3, CloudFront, OAI and Lambda@Edge

I had attempted to use the S3 HTTP endpoint to request the resources from the bucket meaning it was not publicly exposed, however this required a lambda@edge function to route requests as your default index does not apply to sub directories. This gretley impacted my performance when accessing the website and response times could hit 2 seconds. As there are performance limitations with lambda@edge I decided to go with the S3 static with CloudFront.

Future Improvment

In a later post I will explore some more topics arround my site such as monitoring and alerting, expanding the cloudfront and S3 deployment to multiple regions, adding a staging environment and a canary deployment pattern to the “production” environment.