Publishing a blog with Hugo, Amazon S3 and Github Actions

⚠️ Caution: This post assumes thatyou know the basics of shell commands and git.

1
2
3
4
5
TODO
    An existing AWS S3 bucket – This tutorial will use an S3 bucket called gudnex-pail. Be sure the bucket is not blocking public access. When complete, your static website will be available on the Internet and must be accessed publicly.
    An AWS IAM user with various admin rights. The tutorial will touch many different AWS services, so the tutorial is using the root account.
    A registered domain name (optional). If you’d like to learn how to use a registered domain name to host your static website, you’ll need one later in the tutorial.
    A static website or frontend application – The tutorial uses an Interior Consultant GitHub repo as an example.

What is Hugo?

Hugo is simply a static site generator written in Go. In other words, Hugo generates a static website from your content files (actually markdown files). The advantage of static website generators is that you can simply publish static pages to a server without headaches.

By using Hugo you can write your blog posts in

In order to get started, you need to get Hugo. Hugo has several methods to install.

In macOS, you can install

1
brew install hugo

or in Linux

1
2
3
sudo apt-get install hugo
# or
sudo pacman -Syu hugo

For windows, you can get binaries from gohugo.io. After a successful install, you can create a simple blog by just typing

1
hugo new site myblog.com

This command will create a folder which is named “myblog.com” and you will see a bunch of folders in that folder.

  • archetypes: This folder contains frontmatter metadata templates for your blog posts.
  • content: Your content files will be placed here.
  • layouts: Your layout files or HTML templates will be here.
  • static: You can put your static files here (images, pdfs, etc.).
  • public: This folder will contain your generated static site.
  • themes: Themes 😅
  • config.toml: Your configuration file (like site title, description, etc.)

Now, we should install a theme because without a theme we can not render our static site.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Go to blog folder
cd myblog.com

# Initialize a git repo 
git init

# Add our theme as a git submodule
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke

# Add our theme to the config file
echo theme = \"ananke\" >> config.toml

Now we can start our server.

1
2
# We use -D flag because we do not want to hide draft posts.
hugo server -D

Your blog should be available at http://localhost:1313/

Creating an Amazon S3 Bucket

You can follow this detailed tutorial. Also, you can see a summary of steps.

After a successful login to AWS console, go to AWS S3 service and create a bucket with a custom domain name. For our example, our bucket name will be “myblog.com”. You can select any region you want. Unselect “Block all public access”* in order to allow the policy which makes the bucket publicly available, and create the bucket.

Now we have S3 bucket. Go to the Permissions tab and edit the Bucket Policy. In order to enable public access, we need to set up a bucket policy. We will use this policy:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "PublicReadGetObject",
            "Effect": "Allow",
            "Principal": "*",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::myblog.com/*"
        }
    ]
}

This policy will allow any unauthenticated get request to the bucket. Please do not forget to change your domain name. After that, in order to enable static website hosting, go to Static Website Hosting located in the Properties tab. And enable it.

  • The Hosting Type option should be Host a static website
  • The Index Document option should be index.html
  • The Error Document option should be 404.html

In order to test your bucket, create a simple HTML like this:

1
2
3
4
5
6
7
8
<html>
    <head>
        <title>Hello World</title>
    </head>
    <body>
        <h1>Hello World !</h1>
    </body>
</html>

Save the HTML file as index.html and then upload this file to your S3 bucket.

Finally, we have a bucket for a static website. If you want to test your bucket, you can click the link in the Static website hosting section located in the Properties tab. The link will look like

1
http://myblog.com.s3-website.eu-central-1.amazonaws.com

If everything is OK then you should see the “Hello World” page.

Registering Custom Domain

In order to register a custom domain, we will create an Amazon Route 53 zone.

Directing www Subdomain

In order to redirect “www” subdomain to the main domain, we also need a new an S3 bucket. However, the bucket will be empty and it will not contain any files. Its main purpose will be just redirecting to the main domain.

Go to “Create Bucket” page. Name the bucket as www.myblog.com.

Enabling HTTPS Support

** TODO: Not Ready**

Enabling Logging

Github Actions

Extra: Katex Integration for Math posts