Static Website Hosting on Github - Part 1

Table of Contents

Site Hosting

Due to my familiarity with Microsoft Azure, I initially chose to host this blog on Azure, possibly influenced by the fact that hosting a basic static website is free on the platform!

Not long after the successful launch of the thedevopscat.co.uk blog my website became unavailable, after performing some basic checks it became apparent it was nothing that I had done wrong and was in fact a transient issue with Azure. When you are in receipt of a free service, it’s difficult to complain when that service becomes temporarily unavailable, your only real option is to have a backup plan.

To this end I decided to investigate hosting the site on GitHub, which seemed to make sense as the source code and the comments engine are already hosted there.

So rather than complain I decided to look upon the situation as an opportunity to learn and create some new content for the blog at the same time! I set myself a task of trying to make the switchover as seamless as possible, with the minimum amount of self-inflicted downtime, my thoughts were to bring the site up on its native GitHub domain, test, then add a unique custom domain name, once I was happy I could perform the switch of my real site by switching over the target of the existing DNS records in a similar manner.

I started by creating a parallel test site so I could satisfy myself of the process before moving my live site. It turns out hosting a website via GitHub pages is incredibly easy:

Github Website Steps

1. Create a new repository in GitHub that will hold your (compiled) site code. This must be left as public for github pages to be enabled.
2. Name the repo GITHUBUSERNAME.github.io. The name will determine your native URL, however this will be supplemented later with a custom domain. I did not initialise the repo.
3. Go to the repo’s Settings tab, Pages, ensure Pages are enabled (mine were by default), note it uses the main branch to be the source of the website.

Local Steps

I then went to the folder containing my websites Hugo code and performed the following steps:

1. Modified my config.toml file for a new unique base URL on a different domain name prefix, but the same domain (‘www’ element changed to ‘git’) and saved the file.
2. typed ‘Hugo’ with no parameters. (this builds a fully compiled copy of the site with new URL embedded throughout in the /public folder)
3. Then typed the following (standard steps) to initialise the folder as a git repo and push the code up to the new repo (which triggers the build):

cd public
git init
git add .
git commit -m "initial deploy"
git remote add origin https://github.com/GITHUBUSERNAME/GITHUBUSERNAME.github.io.git
git push -u origin main

At this point you should be able to test the site in a web browser by going to your version of: https://GITHUBUSERNAME.github.io/

Initially I left the GitHub page settings in their default mode to deploy from a branch for the ‘classic pages experience’, which seemed to work just fine.

At the time of testing, the alternative github actions option was marked as beta, but I decided to switch to this setting anyway to see what was available. Notably Jekyll is an option, but not Hugo, but we are still at the ‘Static HTML - Deploy static files in a repository without a build’ phase anyway.

The (beta) Pages, Github Action also worked fine for me, so I will stick with this as I likey to add to the actions later.

Adding a Custom Domain

First of all, you need to add your custom domain to your gihub account, this is done in your GitHub user settings, not your repo settings. This will give you a DNS verification text record to create which we won’t go into here as you already did this or something very similar when setting up on Azure static website. Note the first value it gives you is the record name, and the second is the record content (don’t do what I did and not read the dialogue!).

Whist you’re in your DNS provider configuration, you should also add a CNAME record to redirect the traffic from your new FQDN domain name to your GITHUBUSERNAME.github.io.

Once the domain has been verified for use, we can add a custom domain from the repo settings, pages menu, when successfully added your new domain will be queued for automatic certificate creation so now is a good time to go for a well-earned cup of tea! (Mine took just a few minutes).

When the certificate has been created, the cheque box will become available to enforce https and you should now be able to access your website via your custom domain using the GitHub provided automatic SSL certificate and verify the functionality of the site.

This test gave me the confidence that I could move my website within the space of an hour or so, should I need to, which I may do in the future depending on service reliability.

Limitations

An obvious limitation is this is hosting just compiled code in a GitHub repo and assumes the Hugo code is compiled locally, this is so not DevOps!

The way the GitHub actions deployment works for Azure static websites is the uncompiled Hugo website is pushed to a GitHub repo, which triggers the action, the uncompiled code is copied by github action to a runner and the runner compiles the website and deploys straight to Azure. This is preferable as it protects and version controls the source code in a repo, rather than the compiled code.

Next Steps

My next step is to look into the possibility of pushing my uncompiled Hugo code to the first repo, (like I do for Azure), but then run an new action that compiles that code and pushes it to the second (new) repo, which then runs an action to deploy it to GitHub Pages(!).

Then maybe look to do this as a one repo solution with .gitignore work and selective paths for the actions.