Introduction
We’ve decided that instead of starting with boring “hello world”, we can give a glimpse on how our website is set up!
Entire antfarm.it
is built using static site generator
hugo, and runs on Gitlab infrastructure. Thanks to that,
every commit and push to git repository automatically regenerates our website,
and deploys a new version.
Hugo
Hugo generates static pages from Markdown files, so we don’t have to write or style html by hand. It has a variety of available themes, ready to be installed for almost any kind of project.
Work flow is very simple. Once Hugo is installed on a system, it’s a matter of
creating an empty Markdown file in /content/posts
, with following contents:
---
title: "Example Post"
date: 2020-06-29T09:00:00+01:00
draft: true
---
Notice we mark this post as a “draft”. This means it will not show up on our production website until it is ready. Draft posts are only visible when run locally on our machine.
There are lot more post parameters we can use. Check them out in Hugo documentation.
Now we are ready to write our blog post!
To see a preview of our work, we run local server with hugo server -D
, and
point our browser to localhost:1313
. The -D
option allows us to see “draft”
posts.
After we make sure our website looks perfect, it’s time to build it on Gitlab!
Gitlab CI/CD
Gitlab pipelines turn Markdown files into html assets. What we need is
.gitlab-ci.yml
file, with instructions on what our pipeline should do.
Here is a config file from our repository:
image: registry.gitlab.com/pages/hugo:latest
variables:
GIT_SUBMODULE_STRATEGY: recursive
test:
script:
- hugo
except:
- master
pages:
script:
- hugo
artifacts:
paths:
- public
only:
- master
To better understand it, lets go line by line.
image: registry.gitlab.com/pages/hugo:latest
We start our config with defining docker image that Gitlab will use to build our blog. Since we use Hugo, the image needs to have hugo binary installed. For simplicity we went with hugo:latest, which as the name suggest, will build our website with the latest available version of hugo.
After that we have a variable:
variables:
GIT_SUBMODULE_STRATEGY: recursive
Since our base theme (hyde-hyde) is included as a git submodule, we want the pipeline to pull that along with our repository. Without this, our website will not build.
test:
script:
- hugo
except:
- master
pages:
script:
- hugo
artifacts:
paths:
- public
only:
- master
Last two sections define pipeline tasks, which Gitlab will execute upon commit.
Note “except” and “only” keywords. Task pages
will execute every time we push
code to master branch, while test
will run only for branches that are not
master. Both of them execute hugo
script, which will generate static assets.
The only difference between test
and pages
is the latter exports public
path (our built assets), so Gitlab can deploy them.
Gitlab Pages
Finally we can host our website for everyone to see!
Gitlab Pages will setup *.gitlab.io
address for us. However, you can add
your own custom domain. All it takes is a new DNS record. Forcing HTTPS
is a single check box, and Gitlab takes care of generating required
certificates.
This website is open source
To understand setup and file structure, look at our repository. Available here.
If you are looking for help in setting up your own website, don’t be a stranger, reach out to us!