Set up a Local Hugo Development Environment and CI/CD on GitLab for Hugo Modules

post-thumb

Photo by Hasan As Ari from iStock

TinyPilot devices
Table of Contents

The Hugo theme I am using at the time of this writing had several updates which I wanted to incorporate into my site. The most significant update was the refactoring of the theme to make use of Hugo modules. The theme authors created the modules so they could be reused across their collection of themes (once they finish updating them all).

It took some time for me to get my theme and configuration updated to the latest version especially since I have made several customizations. For the most part, I have tried to minimize making drastic changes in case I want to update to new versions of the theme. The process is a lot smoother when most of the files can simply be replaced with the new versions.

Because of the change to Hugo modules, I found that I had to update my development environment as well as the CI/CD configuration in GitLab to deploy the website. I am writing up what I had to do in case it is helpful to others. I had to struggle through the process for a short while until I got everything running properly again.

For this guide, I am assuming you already have Hugo installed, you have successfully deployed a website using a Hugo theme which does not use Hugo modules, and you are now updating the current theme or changing to a new theme which uses Hugo modules.

Development Environment

First thing I had to do was to update my development environment because I could no longer deploy my pages with the built in Hugo development server or the Hugo build command. I am using a Linux based Operating System so you will need to adapt to working in another environment such as Windows.

Update the Go Version

My version of Go was out of date since I was using the packaged version in the Ubuntu repository (I am using Kubuntu as my primary desktop). Just to make sure everything goes smoothly, you may want to use the latest stable version which is 1.20.5 at the time of this writing. Run the following commands to download Go and install it:

wget https://go.dev/dl/go1.20.5.linux-amd64.tar.gz
sudo rm -rf /usr/local/go && tar -C /usr/local -xzf go1.20.5.linux-amd64.tar.gz

Next update your profile in your user’s home directory:

nano ~/.profile

Add the following line to the bottom of the file:

export PATH=$PATH:/usr/local/go/bin

Save the file by pressing Ctrl + O and then Ctrl + X. Finally, refresh your profile by entering:

source ~/.profile

You can verify your Go version by using the following command:

go version

Update the Node.js Version

My primary issue with deploying the Hugo modules was using an older version of Node.js. I kept getting an error on using one of the Node modules. I thought at first it was an old module version it was using but it was Node.js version instead.

Run the following commands to get Node.js installed. The current stable version at the time of writing is 18.16.0:

wget https://nodejs.org/dist/v18.16.0/node-v18.16.0-linux-x64.tar.xz
sudo mkdir -p /usr/local/lib/nodejs
sudo sudo tar -xJvf node-v18.16.0-linux-x64.tar.xz -C /usr/local/lib/nodejs

Just like with Go, you will need to update the .profile file again.

nano ~/.profile

Enter the following at the bottom of the file:

# Nodejs
VERSION=v18.16.0
DISTRO=linux-x64
export PATH=/usr/local/lib/nodejs/node-$VERSION-$DISTRO/bin:$PATH

Save the file by pressing Ctrl + O and then Ctrl + X. Finally, refresh your profile by entering:

source ~/.profile

You can verify your Node.js version by using the following command:

node -v

Build Your Hugo Project

Assuming you have not used the Hugo modules before, you will need to go to the base folder containing your Hugo project and run the following command:

npm install

The Node.js modules should then be installed for your project inside the node_modules folder. Be sure to add this folder to your .gitignore file so that you do not check in all of those modules into your Git repository.

Now you should be able to build your Hugo project containing Hugo modules! While still at the base folder of your project, simply enter the command below to see if your project builds successfully:

hugo

You should also be able to run the Hugo development server as well.

Update Hugo Modules

After getting my site to build, I actually found a bug in the search module used by my theme. I submitted a GitHub issue and the developers fixed it several hours later, which was great. However, I had trouble figuring out how to get the latest updates since I have not had any prior experience using Hugo modules.

Hugo modules will be downloaded automatically and cached in your system’s /tmp folder so I tried deleting the search module buried in that folder, but it must have been the correct folder.

After browsing the Hugo documentation, I found that you simply need to run the following command in the base folder of your project to update all of your Hugo modules for that project:

hugo mod get

This was a good learning experience that I am glad I had because if there are future updates I want to have, I know the process for updating the modules. I never had to do that before because all of the code was shipped as part of the theme, and now the code is downloaded from a GitHub repository.

Update the GitLab CI/CD Runner Yaml File

If you are using CI/CD in GitLab to automatically build and deploy your website, you will need to update the .gitlab-ci.yml file so that it will not error when attempting to build your project. Now that you require both Go and Node.js dependencies, you need those dependencies added to the CI/CD configuration.

This step took some time to figure out until I found an example Hugo GitLab CI/CD deployment on GitLab Pages. The documentation on Hugo’s website does not include such valuable information for building Hugo modules.

The part I needed to add to my existing .gitlab-ci.yml file is the following:

default:
  before_script:
    - apk add --no-cache go curl bash nodejs npm
    - npm install postcss postcss-cli autoprefixer

The configuration above sets up Go and Node.js. I noticed following the example that my deployment failed due to missing npm so when I added that package, everything deployed properly. The full .gitlab-ci.yml file I am using is below. Note that you can use hugo_extended:latest, but I prefer to use the same version as my development machine because I have ran into issues where the deployment failed due to using the latest version.

One more thing to mention is that I also excluded the configuration from the example .gitlab-ci.yml on GitLab where it dealt with themes. Since I already have a theme installed on my site, I do not think it is necessary to specify it like in the example. I think the intention of the example was to make it easier for someone to reuse their example for their own site.

# All available Hugo versions are listed here: https://gitlab.com/pages/hugo/container_registry
image: registry.gitlab.com/pages/hugo/hugo_extended:0.112.3

variables:
  GIT_SUBMODULE_STRATEGY: recursive
  HUGO_ENV: production

default:
  before_script:
    - apk add --no-cache go curl bash nodejs npm
    - npm install postcss postcss-cli autoprefixer

test:
  script:
  - hugo
  except:
  - master

pages:
  script:
  - hugo
  artifacts:
    paths:
    - public
  only:
  - master

I hope you found this information helpful and will save you some time because it was not immediately obvious to me what I needed to do to start using the Hugo modules that my theme was using.

comments powered by Disqus