How Do I Deploy a Hugo Website?

Introduction

In this lab article, we will learn how to deploy a static site with Humanitec. We will use Hugo for that.

Activities

This lab article will cover the following high-level steps.

• Create the Hugo site
• Set up the Github Action
• Create a new app on Humanitec

Prerequisites

• Install Hugo on your machine.
• You need a Github account. Authentication to Github will be done via TOKEN for the direct API interaction and via SSH for the commit.
• Humanitec will deploy the site. Sign up for a free account.

Create the Hugo site

Create the Hugo site locally

In a first step, we will create a new Hugo site and clone the Ananke theme to it.

<p> CODE: https://gitlab.com/christophcrichter/humanitec-blogs/snippets/1988274.js </p>

The code will:

• Create a new Hugo site
• Download the Ananke theme
• Add the theme to the configuration

You can run your site locally to test whether everything is set up correctly.

<p> CODE: https://gitlab.com/christophcrichter/humanitec-blogs/snippets/1988280.js </p>

Visit localhost:1313 in your web browser to see your page.

Create the Github repository for the Hugo site

We will create the Github repository in your Github account and then upload the new Hugo site to it. 

Let’s create a new repository called hugo-app in your Github account.

<p> CODE: https://gitlab.com/christophcrichter/humanitec-blogs/snippets/1988285.js </p>

Where ACCESS_TOKEN is your personal access token for the command line.

We can now commit our page to the newly created Github repository.

The code will:

• Add all files to the index
• Create a commit message
• Set the remote repository
• Commit to the master branch

<p> CODE: https://gitlab.com/christophcrichter/humanitec-blogs/snippets/1988286.js </p>

Create the Docker image for the Hugo site

We can now create a docker image for the Hugo site using Github Actions. All we need is a Dockerfile in the root of the repository. We will use the nginx:alpine base image which is a minimalistic NGINX image based on Alpine Linux.

Create the Dockerfile.

<p> CODE: https://gitlab.com/christophcrichter/humanitec-blogs/snippets/1988292.js </p>

The code will:

• Use nginx:alpine to build static site with Hugo
• Move static content to nginx public folder

<p> CODE: https://gitlab.com/christophcrichter/humanitec-blogs/snippets/1988328.js </p>

We can now commit the Dockerfile to the Github repository.

<p> CODE: https://gitlab.com/christophcrichter/humanitec-blogs/snippets/1988330.js </p> 

Test the Docker image locally (optional)

If you have Docker desktop installed on your machine, you can now test the Docker image of the Hugo site locally.

<p> CODE: https://gitlab.com/christophcrichter/humanitec-blogs/snippets/1988329.js </p>

Set up the Github Action

We are now ready to set up the Github Action to build the Hugo site and to push it to Humanitec. As a preparation, make sure that you have a connection for a Github pipeline with Humanitec. This video explains how to create a connection. We will need the access code as well as the code snippet for the additional step in our Github Action.

Create the Secret

To connect Github and Humanitec, you need to create an Encrypted Secret called HUMANITEC_TOKEN in the Github repository using the token provided by Humanitec.

Create the Github Action

We need to firstly create a Github action in our Github repository. While this can be done from the command line, I prefer to create the Github Action using the web interface. Just go to https://github.com/USER_NAME/hugo-app/actions/new where USER_NAME is your Github user name. Create a new workflow by clicking on set up a workflow yourself.

The main.yaml should look like this:

<p> CODE: https://gitlab.com/christophcrichter/humanitec-blogs/snippets/1988339.js </p>

The code will:

• Trigger Github Action with each new push or pull request to master
• Check out the Github repository
• Check out the submodules (the Github checkout will not do this automatically)
• Build the code and push it to Humanitec

Where HUMANITEC_ORG is your organization name in Humanitec. The new pipeline will be triggered automatically after the commit. Just wait for the Github Action to finish and then head back to Humanitec.

Create a new app on Humanitec

You can now use the image to create a new app on Humanitec. I named my app Hugo App.

Just add the hugo-app image to it and expose port 80.

You are now ready to deploy the new app.

Test the deployed Hugo site

Once the 1st deployment is finished you can visit your Hugo site following the link that Humanitec provides.

Next steps

You have learned how to deploy a static website to Kubernetes from scratch. An interesting use case for this could be to spin up new environments for automatic robot tests. We will pick up this topic in a future lab article. Feel free to contact us (add contact email) with any questions or comments. Or register for one of our Q&A sessions to get in touch with us.

‍

Humanitec is more than just another static website deployment tool. While deploying a static website to Kubernetes might sound like overkill, going through all the steps required to get a Hugo site up and running is a great way to learn about the basic concepts. And it might actually become handy if you want to be able to quickly create additional testing environments for your static website.