tl;dr

This blog post walks you through the detailed steps to create a blog website with AWS and Hugo. The core idea is to simply use AWS’s static-hosting web service and to utilize Hugo, a modern web framework to generate static content for your blog post.

Background Story

Let’s talk about the “Genesis” of this website.

It is the 21st century, and creating a personal website should be really simple, right? When deciding to build one myself, I started scratching my head and looking for content management systems (CMS) such as Wordpress, Drupal, etc. As someone who has experiences of building a few sites using these solutions, I am sure they will work for me.

But wait, where should I host my site, and do I have full access to a (virtual) machine to “do whatever I want” to my website? Realizing that this is no longer the time when I built Stanford’s Graduate Student Council’s website on a workstation that is located in a basement, I began my search in the real-world for an end-to-end solution that meets the following specs:

• Easy to host with low cost
• Lightweight
• Flexible to build a site
• Smooth to deploy

Well, the website hosting vendor isn’t a problem as there are a handful good options such as Amazon Web Service (AWS), Azure Web Hosting, etc. It is nearly a no-brainer decision to choose among those, and I have chosen AWS to host a domain and a website.

What then though? A brief exploration of AWS’s website hosting products reveals multiple options:

• Host a Static Website
• Build a WordPress Website
• Deploy a Node.js Web App
  …

Among the above, the first option “Host a Static Website” certainly serves the purpose of lost cost and lightweight. But can this be a “simple but not simpler” solution for a modern-looking website?

Personally, I like the idea of hosting a site without server-side technologies because this means that you do not have to introduce a full-blown packages and dependencies on the hosting machine (if you can even access it!) even before building something small. After goofing around on the internet, I stumbled upon the concept of Static Website Generator, which turns out to be exactly what I am looking for. As a compiler developer, this idea of writing markdowns and then having a compiler / generator to generate the htmls also fascinates me.

Incidentally, I came upon Hugo, a web-framework that generates static content with speed. After looking around the available templates (which are totally free), I decided to try it out on my machine. The nice thing about Hugo is that you do not have to come along numerous package installations to get things started. If you are a Mac user, just type the following:

brew install hugo

Ok, enough soliloquize. Let’s get into the details about how to build a website like the one you are just looking at :)

1. Set up a web service on AWS

To get started, you need to have an AWS account (of course).

1.1 Purchase / Transfer a domain

Hosting a website requires you to own a domain, and you can either purchase one or transfer one to AWS’s Route 53 service. Since I have purchased my domain directly from AWS, I will walk through the steps.

In your AWS Management Console, search for “Route 53” to find the service to host a domain. In the dashboard of “Route 53”, you specify the domain name you wanted and proceed with the steps to complete your purchase.

After the purchase, you should expect to receive a confirmation email and once it arrives you can click things through to complete the domain name acquisition.

1.2 Configure a S3 bucket for your domain

You need a storage service for your website content, and that is why you need to create a S3 bucket for your domain. This is a non-trivial step as it involves multiple baby-steps of configurations. You should follow the implementation guide detailed on this page from AWS to accomplish step. It took me quite some time to get through this step and successfully launch my site, so I am going to share some tips here:

• It is essential to get the access configuration correct, i.e. set up public access for your bucket before you can test your progress along the way.

• Before you test with your purchased domain, you should test the website endpoint as an incremental step. A website endpoint takes the form of http://bucket-name.s3-website.Region.amazonaws.com or http://bucket-name.s3-website-Region.amazonaws.com, see step 9 of the build.

• If you got stuck in any step here, you should 1) check closely against AWS’s guide and 2) submit a support request. If both these approaches fail, then consider posting your question on AWS’s forum.

Note that if you are with a basic plan on AWS, then you do not get technical support. However, for domain name related question, you can always submit a support ticket under the category of billing.

• Remember to upload an index.html to your S3 bucket and test with your domain.

Once you see your domain up, congrats! You are ready to shape up your own website.

2. Install Hugo and pick a theme

Hugo is easy to install and to use; that is to say the least. For completeness of this section, let me post the command below (again) for Mac users:

brew install hugo

Note: you’d find the quickstart tutorial useful on Hugo’s official site.

Unless you would like to start things from scratch, you’d want a theme, which serves as a template. Fortunately, Hugo has a handful themes descent themes and they are free. Feel free to pick one that suits your need.

Note: you need to install git on your machine as many (if not all) themes assume you have it and provide git command to acquire the theme files.

3. Generate your site and deploy

Congrats! Now you are ready for your development. To test things out, simply launch a web service with Hugo:

hugo server -D

where the parameter server indicates that this is a server service and -D indicates that this is a draft version. Then you should be able to see your website up at http://localhost:1313/ from your own machine.

Now you can deploy your site to S3, and there are multiple ways to do so. First you need to generate all the html files, and you do this by a really simple command, namely

hugo

This generates all the files you need for your website in the ./public folder of the parent folder for your website that you created.

The easiest way to deploy your site is to copy the files in ./public to your bucket.

And that is it! Now you shall see your site up when refreshing your browser.

4. Troubleshoot

Like many engineering practices, you’d encounter issues when you walk through a tutorial, and troubleshooting is an essential step in this context. Below is a list of tips that I’d like to share in this area:

• Do check with AWS support team when you encounter domain name issues.
• When you generate your site content for production, do NOT expect thing would look “normal” when loading the “index.html” locally. This is because everything is generated with a relative path to your baseURL, which is different when running on your local machine.
• Do set draft = false when you want to include a post markdown in your generation. Leaving it with a “true” value would leave no content to be generated for this post.