The purpose of this article is to help you setup a personal blog as quickly as possible using hugo and docker. These are the instructions and notes I’ve written down when setting up my site that I’d like to share.

Please note: In 2020 I originally wrote this article on how to setup a personal blog using hugo. Since then I have become familiar with hugo and felt it would be a great tool to use for setting up a blog project - hence this article. Enjoy!

Assumption

Before I begin, I am assuming you are an advanced computer user and that you are familiar with the following technologies:

  • Docker
  • Hugo
  • Linux Commands
  • Git / Github
  • Golang

If you are an absolute beginning this article might be a challenge for you. I’ve written following articles that may help you get up to speed:

Instructions

Create the HTML Static Pages Code Repository

Before you begin, please create a code repository for the HTML static website that get’s generated by the hugo container.

Log into github. Go and click “New repository” in github and give it a name. Note: Please make sure you at lease include a README file before creating the repository. In our article we will create: bartmika.github.io.

Why that .github.io sort of name? Because in the future, you can use github to host your blog for free.

Create the Hugo Code Repository

The next code repository you need to create is to hold your hugo code. Go and click “New repository” in github and make sure you create an empty cod repository. In our article we will call it bartlomiejmika-hugo.

Then in your terminal clone the project.

cd ~/go/src/github.com
mkdir bartmika
cd bartmika
git clone git@github.com:bartmika/bartlomiejmika-hugo.git

Create the Docker Container

Step 1

We’re ready to begin. Start by creating the volume as follows:

# Create our local volume
mkdir src
docker volume create --driver local --opt type=none --opt device=$PWD/data --opt o=bind bartlomiejmika_hugo_data

# OPTIONAL: In the future if you need to delete the volume you just created
# for whatever reason, you can run the following:
docker volume rm bartlomiejmika_hugo_data

Step 2

Let’s create our container based using the golang:latest image.

$ docker run --name bartlomiejmika_hugo -v $PWD/src:/home/data -p 1313:1313 -it golang:latest /bin/bash

The command parameters are explained as follows:

  • --name bartlomiejmika_hugo - Name our container bartlomiejmika_hugo.
  • -v $PWD/src:/home/data - Map our local projects folder src to inside the container at location /home/data.
  • -p 1313:1313 - The port to bind our project to and map internally to the port inside the container.
  • -it - Attach the current terminal session into the newly created container.

Step 3

Install hugo and confirm it works:

# Save Hugo into our directory.
mkdir $HOME/src
cd $HOME/src
git clone https://github.com/gohugoio/hugo.git

# Install hugo.
cd hugo
go install --tags extended

# Verify that hugo worked
hugo version

Step 4

Create our site. Setup theme. Create first post.

cd /home/data
hugo new site bartlomiejmika

Now please exit the docker container and go back to your original terminal session.

exit

Step 5

In your terminal session, we will add our public folder. Make sure you are still inside the project root. In case you are not, run the following:

cd ~/go/src/github.com/bartmika/bartlomiejmika-hugo/

Let us commit our root project so we will have a main branch setup - which is necessary for us to use submodules.

git add --all;git commit -m 'Initial commit';

hugo already created a public folder, we will remove it now.

rm -Rf ~/go/src/github.com/bartmika/bartlomiejmika-hugo/src/bartlomiejmika/public

hugo already created a .git folder inside of the container. We don’t want to use it, we want to use the .git found in the project root, as a result delete it.

rm -Rf ~/go/src/github.com/bartmika/bartlomiejmika-hugo/src/bartlomiejmika/.git

Integrate with our bartlomiejmika repository.

git submodule add git@github.com:bartmika/bartmika.github.io.git src/bartlomiejmika/public

Why did we this? Now whenever we generate our HTML static content, it will be outputted to the public folder which is another code repository. We can save the changes in the code repository and it will update our production server.

Step 6

Next we want to install a theme and create a first post. To begin, let us add submodule into our project for the theme.

# Make sure you are still in the project root. In case you are not, run the following:
cd ~/go/src/github.com/bartmika/bartlomiejmika-hugo/

# Integrate with a theme.
git submodule add https://github.com/adityatelange/hugo-PaperMod src/bartlomiejmika/themes/PaperMod

Here we will setup our theme.

# Open up an existing container. If you get `You cannot attach to a stopped container, start it first` error message, then run the next two instead:
docker attach bartlomiejmika_hugo

# OPTIONAL: Or start the container and open it up again.
docker start bartlomiejmika_hugo
docker attach bartlomiejmika_hugo

# Go back to our location.
cd /home/data/bartlomiejmika/

# Next add our theme configuration
echo 'theme = "PaperMod"' >> config.toml

# Create our first post.
hugo new posts/my-first-post.md

Step 7

Finally run the server.

hugo server --bind 0.0.0.0 -D

Open in your favourite web-browser: http://127.0.0.1:1313.

If you see the web-page, congratulations, you have successfully setup the project. Spend some time reading through the developer documentation.

Additonal Notes:

Note 1: Deployment

When you are ready to deploy, stop the server and run the following.

# Recompile the web content.
hugo --minify

# Exit the docker container
exit

# Commit the web-content to the repository. Once committed
# you can setup triggers in your code repository to deploy
# the HTML static pages to your site.
cd public
git add --all;
git commit -m 'Some commit.';
git push origin master;

Note 2: References

Special thanks goes to xa1.at who wrote Installing Hugo (or anything else) into a Docker Container that was very helpful.

Note 3: How do I deploy to the internet?

Please checkout the following article I’ve written via How to Start a Personal Blog With Hugo a Static Site Generator Written in Go (Part 2).