Continuously Deploy a Hugo blog with GitHub Actions, Docker and a VPS

Disclaimer: In this tutorial I will just explain my solution for a problem that I had. If you have any suggestion feel free to contact me!

In August I decided to create a new blog where I can post some stories about Machine Learning, my idea is to publish these stories in italian (I’m a native speaker) because I believe that for some topics there are not a lot of informations in italian.

To create this blog I had some constraints:

• I wanted to write the posts using Markdown;
• I wanted to publish the posts without using a dedicated admin website (like the one that I have if I use Wordpress);
• I wanted to use my new VPS to host the website;
• On the VPS (It is a shared VPS) we only use Docker so I had to use Docker also for this project.

To solve my problem I decided to use Hugo, an open source static site generator, Github Actions and Docker on my VPS.

Let’s see how to generate our Hugo website and continuously deploy it using Github Actions and Docker.

• First of all you have to install Hugo, here you can find all the informations about that.
• After this first step you can create a new folder on your computer and then you can create a new Hugo project into this folder:

mkdir HugoTest
hugo new site HugoTest

• If everything goes well you will find a new folder containing some folders like “archetypes”, “data” and “content”.
  Some of the folders that Hugo created are empty, you have to create a “.gitignore” file in each of the empty folders.
  The “.gitignore” must contain the following text:

!.gitignore

• Now you can create a new GitHub repository.

• Now you can follow the setup provided by GitHub when you create the new repo, move in the Hugo project folder and, using your terminal write the following commands:

git init
git add .
git commit -m "First commit"
git remote add origin https://github.com/<USERNAME>/<REPO>.git
git push -u origin master

• You should see this in your repo:

• We can now setup the synchronization with the VPS using GitHub Actions. Let’s move to our VPS and create a new folder for this project.
  Now we can clone on the VPS the repo that we created:

git clone https://github.com/<USERNAME>/<REPO>.git

• Now you have to generate a secret token on GitHub, you’ll need this for the Action. You have to go to your’s profile setting -> “Developer Setting”. -> “Personal Access Tokens” -> Generate new token.
  You have to copy the generated code, you will need it for the next step.

• Now we can add some secret informations to our repository, go to the “Settings” tab and then to “Secrets”

• We have to add some secrets parameters that we will use in our GitHub Action. Click su “New Secret” and add the following parameters:

PROJECT_PATH

PROJECT_PATH is the path of the repo that you cloned on your VPS, in my case is /home/luca/TestHugo/TestHugo

SERVER_IP

The IP address of your VPS

SERVER_PASSWORD

The vps’s password

SERVER_USERNAME

The username that you use to login to your VPS

TOKEN

The token you generated in the previous step.

• Now we can setup our GitHub Action, you have to go to the page of your repo and the click on the “Actions” button, then you have to click on “Set up a workflow yourself”.

• In the Action’s editor add the following code:

• Commit the Action clicking on “Start commit” and then to “Commit new file”.

• If you go to the Actions tab you will see the actions that is running and if everything is ok you will see something like this:

• Now you have to choose the theme of your blog, in this tutorial we will use Harbor, on the VPS you have to use the following commands:

git submodule add https://github.com/matsuyoshi30/harbor.git ./themes/harbor
echo 'theme = "harbor"' >> config.toml

• Now we can setup the Dockerfile, in Hugo project’s folder you just have to create a file called “Dockerfile”. Paste the following lines in the “Dockerfile”:

• In the same folder you have to create the file “docker-compose.yml”:

• Now you can launch your docker container using the command:

docker-compose up 

If everything is ok you should see something like this:

If you connect to the IP of your VPS using the port 1313 you should also see your newly created blog:

• Now we can do some tests, on the VPS you have the running container and on you local machine you have to create a new blogpost, you can use the following commands:

hugo new post/test.md
nano content/post/test.md

• Set draft to false and save the markdown file:

• Now you have to push the new file to Github, the actions that you have created in one of the previous steps will start running and if everything is ok you will see this:

• Now we can connect again to our blog using the IP and the port 1313.
  If everything went well you should see the new blog post:

• Now on the VPS we can kill the “docker-compose up” command and if we want to maintain online our website even if we close the connection to the VPS we can launch it again using the -d option:

docker-compose up -d

Conclusions

That’s all for today, I hope that this tutorial was useful for you, if so, clap your hands!

If you have any suggestions feel free to contact me on Twitter or just leave a comment here.