Hosting Hugo on GitLab

A short overview of what I did to host this Hugo based website on GitLab.

Bryan Klein

5 minute read

I recently decided to switch from Wordpress to a Static Site. This post is a review of what I finally ended up with for the most simple solution for my site. I had a few guiding principles as I worked through the process of setting this up.

  • Free or Cheap static site hosting
  • As few moving parts and systems as possible
  • Easy to create or update content from desktop or mobile
  • Supports SSL (HTTPS) for my domain

I tested many different tools and configurations before I ended up where I am now. Here are a few of the sites/services/tools that I worked with at some part during my testing phase.

  • GitHub (Repository)
  • GitHub Pages (Hosting)
  • Google Firebase (Hosting)
  • Amazon S3 Bucket (Hosting)
  • Amazon Route53 (Necessary for S3 Bucket Hosting)
  • Travis-CI (Hugo Builds/Deployment to Firebase Hosting)
  • GitLab (Repository, CI Builds and Hosting)

Now, lets go over what I ended up with and why.

Hugo

Because Hugo is fast and easy to setup.

GitLab

I was familiar with GitHub and knew about GitLab, but had not had much experience with it yet. I am glad that I took the time to check it out. This one system allows me to host a private repo of my site content, build a Hugo site when there is a commit to the master branch and deploys the static content to GitLab pages. This is what I was looking for. See this page on the Hugo site about Hosting on GitLab. A side benefit of GitLab is that I already had a Hugo site setup in my GitHub repository. It was really easy to import the project over from GitHub to GitLab and continue on from where I left off.

GitLab CI

GitLab has a built in Continuous Integration/Deployment system, so no need for some external worker like Travis-CI, drone.io or Werker to do it for me. Just by creating a config file in the root of my site repo, I was able to trigger builds of my Hugo site and deployment to GitLab Pages. See my CI configuration file for how easy it is. Note: this configuration if for Hugo version 0.18, you would need to make changes as needed for whatever version is released now.

GitLab Pages

GitLab has a feature similar to GitHub for hosting static site content, but I think it is a bit easier to use. It was also very easy to setup SSL for my custom domain which GitHub Pages cannot do now. In addition, paired with the Continuous Integration/Deployment feature, it would be just as easy to use any other static site generator and not just Hugo. I am a big fan of Hugo and having my site content updated in less than 30 seconds after a commit to the master branch is fantastic.

Google Domains

I really like the simplicity of the Google Domains UI and I already had my domain registered with them, so this was the easiest part. I did have to change the A record to IP 104.208.235.32 for GitLab pages, which was quick and easy.

StartSSL

Here is a document on how to setup StartSSL for your GitLab Pages custom domain. Please note the step to use the NginxServer archive and the contents of the bundle file for your certificate information. I wasted a little time by not seeing that bit on my first pass.

Editing Content

Forestry.io

I have been looking for an online editor for my Hugo content. There are many online Markdown editors, but few easily connect to a GitLab repository, Forestry.io does this easily. The support for their service is amazing too, they quickly reply to chats and email. I look forward to working with them. Note: they also offer a build/deploy feature, but for my setup I don’t need that. When the files/changes are pushed to my GitLab repository from Forestry.io, the build and deploy happens on GitLab and not on the Forestry side.

Mobile

I have an Android phone, and I have found the combo of Pocket Git and DroidEdit Pro to be a powerful one. I can open a file from Pocket Git in DroidEdit, make some changes and save it. Mark the edited files for commit and then Push the changes to my GitLab repo. As soon as the commit hits the repo, the build is triggered and within 20 seconds my site is updated. I am currently looking for a nice Markdown editor for my Android Phone/Tablet that will make editing with real-time preview of the Markdown easy.

Desktop

I use MarkdownPad2 and Sublime Text 3 for local edits on my desktop. There are many nice editors out there with Markdown preview, so find what you like.

Summary

To wrap this up, here is a basic list of steps in order that you would do to make a Hugo site on GitLab from scratch.

  1. Create an account and project for your site on GitLab
  2. Use SourceTree to clone your site to your local computer.
  3. Setup Hugo on your local computer.
  4. Initialize a new site with Hugo in the GitLab project folder you cloned (Will need the –force flag.)
  5. Work locally to setup the Hugo site as you want it with some basic content and a theme.
  6. Commit and then Push your site to GitLab, with the CI file as I have linked to above in your Hugo root folder.
  7. This should trigger the CI build and deployment to GitLab pages with your site to https://[username].gitlab.io/[projectname]
  1. Register your custom domain with Google Domains
  2. Create a StartSSL certificate for your domain.
  3. Setup your Custom domain with your Certificates and Private Key in GitLab Pages settings.

That’s about it, please ask any questions or give suggestions for edits below.

comments powered by Disqus