Environment & Hosting Setup

Create the Repos

I created two repos on GitHub. One private for all the source code and one public for the hosting. While the private repo’s name doesn’t matter too much, the public one needs to be {github_username}.github.io in order to use the root of the GitHub pages domain. For example, if the repo was named hugo, the url generated by GitHub pages would be https://{github_username}.github.io/hugo. I found this out the hard way, but cest la vie.

So my two repos are

• https://github.com/TChilderhose/tchilderhose.github.io_source (Private)
• https://github.com/TChilderhose/tchilderhose.github.io (Public)

Private Repo + Hugo Setup

I cloned my private repo to where I wanted my local env and started setting up the site structure.

Grab Hugo Executable

The great thing that I really like about Hugo is that all you need is this executable and that’s really it. No dependencies or anything.

To keep it as portable as possible and not reliant on the OS’s repo or package managers, I grabbed it straight from the GitHub. Go to the Hugo GitHub repo and get the latest hugo extended executable, which at the time of writing was hugo_extended_0.82.0_Linux-64bit.tar.gz. I extracted it into my repo and placed it into a ./bin/ folder. The reason for the extended version vs the normal is that it adds the functionality for SASS/SCSS and PostCSS, both of which I plan on using.

Create Hugo Site

To create the site, I called

./bin/hugo new site temp

And copied all of the contents of ./temp/ out and into the root directory.

I think this would have worked as well

./bin/hugo new site --force . 

but I did it the hard way.

Grab a theme

I downloaded a theme from it’s GitHub repo as zip and placed it into the ./themes/ folder. Guides online suggest either cloning or creating a submodule, but I knew I would be editing the theme a lot, so I decided to keep it tracked in my private repo.

Public Repo

The way that hugo works, is that it builds the entire site into the ./public/ folder by default, ready to be hosted (apache www folder, GitHub Pages, etc.)

In the root of the Private repo, I deleted the ./public/ folder (if there was one) and cloned the public repo to that folder

git clone https://github.com/TChilderhose/tchilderhose.github.io public

That way I can now build the site, cd into that directory and push it up to GitHub.

Hosting Setup

To begin, lets make a build and push it up

//deploy.sh
find "./public" -mindepth 1 -maxdepth 1 -not -name ".git" -not -name "CNAME" | xargs rm -R
 
./bin/hugo --minify -d public

cd public
git add .
git commit -m "Latest build"
git push origin master
cd -

This is one of my helper scripts that I made. It will

• Clean out the public directory, leaving the /.git/ folder and the CNAME file that gets created by GitHub in the next few steps.
• Make a minified build of the site into the ./public/ folder
• Goes into the folder, commits and pushes and backs out

Once it’s pushed up, go to the GitHub repo’s settings. Scroll down to the GitHub Pages section and select the master (or potentially main) branch from the dropdown and click save. This will deploy the site to https://{github_username}.github.io.

Now each time the repo is updated, it will re-deploy the site. Neat.

DNS Setup

This is the part that I didn’t find a whole lot of information online and had to tinker a bunch with. Basically, I wanted to use my own domain, tchilderhose.ca, for the GitHub Pages site. But I also wanted all the subdomains to go to my home server.

This is what I did to get it to work on Cloudflare.

• The A setting is set to wildcard and points to my home server’s ip. This takes care of all the subdomains
• A CNAME setting for @ (or tchilderhose.ca) that points to tchilderhose.github.io
• A CNAME setting for www that points to tchilderhose.github.io

Going back to the GitHub Pages settings page on the repo, I set the Custom domain field with my domain. This adds a CNAME file in repo with the domain.

Once I did this, the site was using https://tchilderhose.ca!