Weekend Project: Building this website with Hugo

Intro

My old website was built with Octopress, a Jekyll-based blog platform which has now ceased development. While I don’t have intense requirements for a simple blog, I saw an opportunity to learn some new things.

There are numerous options for blogging, from writing your own HTML and CSS to posting on Tumblr. My goal for this site is to balance control over content and publishing with long-term ease of use. Hugo fits that goal with a little work up front and simple Markdown writing. In addition, I wanted to get my hands dirty with version control and HTTPS to partially simulate running a more serious website.

The Toolbox

• OS: Fedora
• Editor: Visual Studio Code
• Framework: Hugo
• Version control: Gitlab
• Hosting: Amazon Web Services

Dev Environment

Before even touching AWS, Hugo lets you preview what your site will look like with a built-in webserver. My first attempt to run Hugo with Git and VS Code failed horribly on Windows, so I built a Fedora virtual machine to give myself a better experience with the command line and snapshots if I really mess up.

Installing the toolbox is pretty straightforward; git is built-in to Fedora, Microsoft provides a stable yum repo for VS Code, and Hugo is a single binary you can throw into /usr/local/bin.

Configuration of the environment is a little more complicated. To integrate Hugo, Gitlab, and VS Code I used the these steps:

1. Create a new repository in Gitlab
2. Set up SSH communication with Gitlab and test that the remote server is in ~/.ssh/known_hosts and ~/.ssh/config

3. Run the following commands from your working directory

   $ hugo new site <SITE_NAME>
   $ cd <SITE_NAME>
   $ git init
   $ git remote add origin git@gitlab.com:<username>/<repo_name>.git
   $ git add .
   $ git commit -m "Initial commit"
   $ git push -u origin master
   

4. In VS Code simply open the <SITE_NAME> folder (Ctrl+O) and the git config should load automatically allowing point-and-click staging, committing, and pushing.

Now load up the Hugo theme library and take one for a spin. In my case I chose One for its simplicity. Most likely git will ignore the theme files from a clone, so don’t be surprised if they don’t get pushed to your personal repo.

My basic workflow is almost entirely in VS Code. I can run hugo server to preview the site in Chrome and hugo new posts/<POST_NAME> to generate a new page. There are many extensions available as well to help with Markdown and TOML. One really cool extension is Bracket Pair Colorizer which helps greatly if you need to dive into a theme’s CSS and HTML.

Hosting on AWS

S3

With a finished source, run hugo to build the files for deployment to a web server. In this case the server is AWS S3 configured with static website hosting. It’s simple enough to use the S3 management console to drag and drop the files in the public directory and be done with it.

Route 53

Configuring DNS with Route 53 is also a simple AWS doc. The example Bucket Policy can be skipped as that will be handled with CloudFront.

CloudFront and ACM

Finally, adding HTTPS requires CloudFront delivery for the S3 bucket. Create a new distribution and select the bucket in Origin Domain Name. Set Restrict Bucket Access to Yes. An Access Identity is required for this, either make a new one or reuse an existing one. CloudFront will automatically update S3 permissions when you set Grant Read Permissions on Bucket to Yes, Update Bucket Policy.

In Default Cache Behavior Settings I set Viewer Protocol Policy to Redirect HTTP to HTTPS and Security Policy to TLSv1.2_2018. Then for Alternate Domain Names (CNAMEs) enter the domain name of the site.

While CloudFront initializes the distribution, it’s time to request a certificate. In Certificate Manager enter the domain name and select DNS validation. AWS makes this a one-click affair by creating the required DNS record in Route 53 for you with a big blue button. Once the validation is complete, go back to CloudFront Distribution Settings and set SSL Certificate to Custom SSL Certificate (example.com). The ACM cert should be present in the drop-down.

This isn’t a complete guide to CloudFront, but it’s enough to get started for a static site. There are lots of great resources to learn more, such as this open guide for almost all AWS services.