Hugo Website Auto Rebuilds with Jenkins

This article will work through setting up on demand HUGO Website site updating to your ssh based webserver via github and jenkins.

Problem I am trying to solve.

After years of having to deal with wordpress security issues (plugins, wordpress itself, php, etc), I have decided to go static webpages like in the “old days”. I decided to give HUGO a try. I can write my documents in Markup, and have it generate the website with any theme I want. Then I just have to upload it. Wouldn’t it be nice to be able to edit the site locally, commit/push it in git, then have the magic of the the Internet render it and upload it to my webhost for me?

Software Packages I will need

Lately, my editor of choice has been Visual Studio Code. It runs on my macbook, my windows machines, and a linux desktop if I had one. With git installed, and intergrated into VS Code, the only things left are a git repo hosting service, and a continous delivery platform.

Since I already have a Github account, I decided to just use a private repo with it. It has webhooks that can integrate in with any continuous delivery system. You can also use Gitlab if you want to. This would let you selfhost if you wanted to go that route.

Finally, we need something to run our build environment and to publish to our webserver. There are many choices, from using the built in GitHub Actions inside Github, to self hosted solutions like Jenkins or Travis CI. I decided to go with Jenkins.

Putting it all together

Visual Sudio Code and Git are integrated. There are many howtos on the internet to set that up. I wont go over that.

The fun starts with setting up Jenkins and Github to work together. First, I fired up a docker image of jenkins. I decided to use the recommended version from the Jenkins site itself. I fired up jenkinsci/blueocean inside my docker swarm. I made sure to use persistant shared storage with the container, so it could move across hosts as I did maintenance on the swarm. With that up and running, I enabled security so it required authenication from my LDAP directory to get in. Now that I had jenkins up and running, I started building a pipeline.

The Jenkins Pipeline

Yes, I installed blue ocean, but that wasn’t as straight forward as I had hoped it was. I instead decided to just start a regular Jenkins pipeline. I named it after my website so I could find it easier when I added more jobs inside Jenkins.

I made the following Changes

Enabled GitHub Project and put in my project url
Git Source Code Management.
For Repositories URL, I used the ssh url.
I added a ssh key that could push code to the github repo into the credentials.
I did add Advanced sub-modules behaviours to the Additional Behaviours. This let me recurisive update submodules (this will be important later)
GitHub hook trigger for GITScm polling
Execute shell in the build steps: /path/to/perstistant/storage/hugo/hugo -b “https://websiteurl.com”
Post build Send build artifacts over SSH with source files being public/**
Remove prefix public
Advanced -> Clean remote checked.

If you have the credentials setup right (for SSH into your webserver, and to github), then you should be able to manually kick off your build and have it send files to the webserver. When you view the Console Output, after (or during) a build, you will finally see the following lines.

+ /var/jenkins_home/hugo/hugo -b http://n3bbq.org
Start building sites … 

                   | EN  
-------------------+-----
  Pages            | 19  
  Paginator pages  |  0  
  Non-page files   |  0  
  Static files     | 32  
  Processed images |  0  
  Aliases          |  5  
  Sitemaps         |  1  
  Cleaned          |  0  

Total in 136 ms
SSH: Connecting from host [7c9efeb134da]
SSH: Connecting with configuration [n3bbq_website] ...
SSH: Disconnecting configuration [n3bbq_website] ...
SSH: Transferred 64 file(s)
Finished: SUCCESS

This shows that Hugo build the website, and stats for that build. Then it shows SSH connection to the host, and that it transfered files. Next, we need to get github pushing notices to us so we can auto build when there are commits (since I am a 1 person crew, Pull Requests seemed silly to trigger off of).

The magic settings to get GITHUB webhooks running automatically

If you go to the Manage Jenkins link (at the top level of the site), you will see Configure System. Once you click it, you will want to make sure you set the Jenkins URL to a URL that will get back to the server. It will use this to push the config to github once you configure it.

Next, move down to GitHub and Add a GitHub server. You will need to add new Credentials. It is very important to change the type to Secret Text. You will need to generate a Personal Access Token(PAT).

####This PAT will need the following permissions

admin:repo
repo
repo:status

Once you have the PAT string, put it into your new Secret Text credential. This is very important that it is Secret Text. Once you have that done, you can save and it should push the webhook settings into the github repos you have linked in your pipelines. You can see this in the settings area of Github for your linked repo. Inside webhooks, you should see your jenkin’s URL address. This should have a checkmark next to it. That means everything is good to go. The next commit/push to github to the branch you selected will fire off the build and send the output to the webserver.