Hello, we are Antfarm!

..and this is our static site setup with Gitlab.

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.

Gitlab CI/CD

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.

Gitlab Pages

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!