Introducing colby.gg

The goal of colby.gg is to document the things I find interesting. This includes my HomeLab setup, software practices, and other bits and pieces that may be useful to reference in the future.

Hopefully someday colby.gg will become a useful reference.

Tech Stack

Site generation is done using Hugo

Hosting service is currently GitHub Pages with a custom domain

Deployment is done via Github Actions

Steps

0. Create a github repository with a name matching:

   ${GITHUB_USERNAME}.github.io

   If your github username is SillyWilly, then he repository name must be SillyWilly.github.io.

1. Install Hugo locally

   Hugo has fairly good installation and quick start instructions.

   For WSL environments I found downloading the latest release and placing the hugo binary at /usr/local/bin/hugo worked best.

   Make sure to download the extended version

   The extended version is more likely to work with any themes you choose. The commands below should work for WSL or plain linux.

   cd /path/to/Downloads
   tar -xvf hugo_extended_0.119.0_Linux-64bit.tar.gz
   sudo mv hugo /usr/local/bin/
   

2. Follow the Hugo quick start instructions.

   Example init command:

   git clone https://github.com/MrUsefull/MrUsefull.github.io
   hugo new site MrUsefull.github.io --force
   

   The above snippet is the only deviation I took from the Hugo docs.

3. After completing the quick start instructions, running hugo should create the public directory. For this setup, do not commit public directory. Commit all other files and push to your github repository.

4. Create the github action. Once again Hugo has great documentation for this. Quick warning: Double check the branch in the github actions yaml is the default branch you use. The documentation’s example uses main.

   Once the github action changes are pushed to the default branch, your site should be available at ${GITHUB_USERNAME}.github.io

5. Use the project settings page to set the custom domain to the domain or subdomain you already own.

   You probably also want to verify your domain.

   Github’s instructions differ between subdomains (foo.example.com) and apex domains (example.com).

6. Write this post!

Troubleshooting

When using Cloudflare for DNS on a custom domain, github pages gives the following error:

The page isn’t redirecting properly

The solution is to disable cloudflare proxy for the domain or subdomain pointing at github pages.