Going Strange Places

On the travelling and everything else

Built with Hugo ❤️ hyde-hyde.

On How This Website Was Built

2019-10-16
7 min read

This first post does not have anything to do with traveling, but on how to I set up this website. It was surprisingly easy and the whole deployment process is awesome.

First of all, you might have already seen it in the sidebar, this website is powered by Hugo. Hugo is a static site generation written in Go. If you are not familiar with static site generators I will give you a quick break down. The name already hints it, it creates a static site, meaning that no external resources like a database or server side code is needed to render the website. We basically have HTML, CSS and JavaScript. This post for example was written in Markdown. Hugo takes this Markdown code, adds the configured theme (which is the beautiful hyde-hyde) and then generates the static website, ready to be served by a web-server.

The advantages of this approach are:

  • Lightweight, simple websites.
  • Content can be added easily.
  • No complex technology needed.
  • Security! Most security vulnerabilities are mitigated by design. (no server side code, no database, …)

The Hugo developers are much better at explaining how to create a website with Hugo. Head over to their documentation to get started: https://gohugo.io/getting-started/quick-start/. It literally takes 10 minutes to have your website.

We got a static website now. But how can we serve it to users? You could use any web-server for this, but for simplicity I recommend AWS Amplify. Deploying your static website with AWS Amplify is like doing magic. The process is basically to put your code in some version control system like Github (public and private repositories supported) and then configure your Github Project on AWS Amplify. AWS Amplify will automatically recognize your code as Hugo code and build it automatically. If you change something and push these changes, Amplify will automatically detect this and rebuild your site. It will also automatically serve it over CloudFront, auto scale and do all that AWS magic. The whole process is also in the Hugo documentation: https://gohugo.io/hosting-and-deployment/hosting-on-aws-amplify/.

Just one more thing: avoid cluttering your Git history with the HTML files of your static website. Add the following line to your .gitignore to not commit the built files in the public directory. AWS Amplify builds these files anyways.

# Hugo output directory - AWS creates this
/public

We now got an up and running website, but there is more we should do:

  • Configure a domain for your website.
  • Add a dev branch to your repository and point to it.
  • Adapt the build settings.
  • Configure your Hugo website.
  • Create some content!

Configure a domain

I would recommend to use AWS Route 53 for domain registration, just because it is easy to use and integrates the well with other AWS services. It is most probably not the cheapest option though. If you use Route 53 for domain registration or transfer a domain to Route 53 you can configure the used domains in the “Domain Management” section in AWS Amplify.

Add a dev branch

You should add a dev branch to your repository. Just create a dev branch and push it to Github:

git checkout -b dev
git push --set-upstream origin dev

Use this dev branch for work in progress. When you are done writing a post, and have verified it, merge dev to master:

# merge master into dev
git checkout dev
git merge master
git push
# merge dev into master
git checkout master
git merge dev
git push

To prevent accidental commits on the master branch you can set a pre-commit hook. These can only be set locally, so you have to create them on every system you are developing. To create a pre-commit hook create the following file in .git/hooks/pre-commit:

#!/bin/sh

branch="$(git rev-parse --abbrev-ref HEAD)"

if [ "$branch" = "master" ]; then
  echo "You can't commit directly to master branch"
  exit 1
fi

To have AWS Amplify build your dev branch you have to point to it. Configure it under General -> Branches. You can then find the domain of your dev website under Domain Management. It is advisable to require login to access the dev website. You can configure this under Access setting. Add username and password authentication to your dev website.

Adapt the build settings

You will now want to adapt the build settings. The out of the box settings work but are not optimal. This is my config:

version: 0.1
frontend:
  phases:
    build:
      commands:
        - if [ "${AWS_BRANCH}" = "master" ]; then hugo; fi
        - if [ "${AWS_BRANCH}" = "dev" ]; then hugo --buildDrafts --baseURL="https://dev.<YourAppID>.amplifyapp.com"; fi
  artifacts:
    baseDirectory: public
    files:
      - '**/*'
  cache:
    paths: []
  customHeaders:
    - pattern: '**/*'
      headers:
        - key: 'Strict-Transport-Security'
          value: 'max-age=31536000; includeSubDomains'
        - key: 'X-Frame-Options'
          value: 'deny'
        - key: 'X-Content-Type-Options'
          value: 'nosniff'

There are two changes in the config. First of all I added a dev branch specific configuration. I want drafts to be built in my dev branch, to be able to look at my post before I publish it. I also want to adapt the base URL to point to the dev website, so that links in the website do not redirect me to the master website.

I also add some HTTP security headers to the responses, to enhance the security a little bit more:

The Strict-Transport-Security header is important, because it prevents loading the website over unsecured connections, preventing SSL Stripping attacks.

The X-Frame-Type-Options header is set to deny, to prevent another website from embedding this website as an iframe. This could be misused for a clickjacking attack.

The X-Content-Type-Options header is set to nosniff, to prevent browsers from guessing the content of a site. This is particularly useful if users could upload data. Even though they cannot, it does not hurt to set it.

But wait, aren’t there more headers we could set? I especially recommend to set a Content-Security-Policy header, but this one is a little bit more complicated and depends on the theme you are using, therefore I am not setting it at this time. The other headers are not so important right now, important is to know how to set headers. I might write another post when I got this up and running.

Configure your Hugo website

You should now configure your Hugo website. Just edit the config.toml file. This is my configuration:

# the title of the website
title = "Going Strange Places"
# the used theme
theme = "hyde-hyde"
# the url of the website (can overridden when starting Hugo with baseURL)
baseURL = "http://goingstrangeplaces.xyz/"
# the language we use
languageCode = "en"

# enable robots txt, without further configuration it just allows everything
enableRobotsTXT = true

[params]
  # the subtitle
  description = "On the travelling and everything else"
  # configuration of the theme, this is its color
  themeColor = "theme-base-0f"

  # the date format to use
    dateformat = "2006-01-02"

    # sidebar, copyright & license
    showBuiltWith = true

    # https://highlightjs.org
    highlightjs = true
    highlightjsstyle = "github"

## Main Menu
[[menu.main]]
    name = "Posts"
    weight = 100
    identifier = "posts"
    url = "/posts/"
[[menu.main]]
    name = "About"
    identifier = "about"
    weight = 200
    url = "/about/"

Create some content!

That was all the configuration to get a basic site. Let’s create some content. To create content from a template just type the following command:

hugo new posts/my-first-post.md

This creates a content from a template in posts/my-first-post.md. Write your content in this file and commit and push your changes. Your content will appear on your dev website. When you are happy with your content remove the draft: true from the top of the file, commit the changes and merge them to master.

That’s it! Of course setting up a website is not a one time thing, it is a process. I am still new to Hugo and still have to learn lots of things. I might write another post soon, when I have got more stuff working. There is always something to do!

Interrail Economics