April 19, 2024

My Struggle with Hugo in Docker

This is a post to document the issues I stumbled upon when setting up my resume website.

Firstly, why did I choose Hugo ?
Because it's written in go, that's the only reason. As a golang lover, I thought it would be more fun to work with it. Until it proved me wrong...

Currently I'm running my services on docker, managed by Portainer, so I wanted to spin up a container to run the server. Somehow I got into different issues for all the official/unoffical images I tried. I've also run the image from the Dockerfile in the official repo, but it wasn't straightforward and I had to resolve some dependency issues.
Eventually I used the image klakegg/hugo:ext-ubuntu to build my container.
Here's the simplified yaml file:

server:
    container_name: hugo
    image: klakegg/hugo:ext-ubuntu
    command: server
    volumes:
      - "/mnt/hugo:/src"
    ports:
      - "1313:1313"

This is just the beginning of my nightmare though.
To run the server, I had to jump through some hoops to make it work.
The first issue is the container terminated immediately after I created. This is the error I got:
Error: Unable to locate config file or config directory. Perhaps you need to create a new site. Run `hugo help new` for details.

This happened because there was no config file as no website had been created yet. To solve this problem, I simply created a config.toml file in the working directory:

baseURL = 'http://example.org/'
languageCode = 'en-us'
title = 'My New Hugo Site'

So the error is now gone, I started a website by following the guide.

Another caveat here, after running hugo new site quickstart, I had to move out all the contents from quickstart, because of the hack I did earlier.

Here comes the second problem - I found out the rendered html does not point to the page correctly, which caused the failure of loading all the static files.

but I had already set the baseURL !??

Apparently the baseURL in the config is ignored. This is a very weird behavior in hugo. To mitigate the issue, I had to change the docker command:

'server' '--baseURL=http://example.org' '--appendPort=false'

# entire command would be:
hugo server --baseURL=http://example.org --appendPort=false

Voila ! The website is rendered correctly !

I've tried several free templates, but unfortunately many of them have some npm/js/css problems when I tried to apply. I'm not a FE person and didn't bother solving the library issues, so I just picked the simplest one. 😎

Reference