Introduction

I've been working with Civo for a year now, and the truth is that I can't ask for more - it's great working for a cloud company like Civo and with great co-workers. I get to play around with the technology and when I discover something cool, I can write a guide on it. So here is another one! By the end of this you will have a blog site running on Kubernetes that you can continuously deploy without interruptions with each commit to your repository.

What is Hugo?

According to the official site:

The world’s fastest framework for building websites

Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again.

The Core

To follow along with this guide, you will need to have a Civo #kube100 account. You can sign up here and if approved, you will get $70 monthly statement credit for the duration of the beta, meaning following along will be entirely free for you!

You will also need a GitHub account where you can set up a repository, your Civo API key and a Docker Hub account.

We will skip explaining k3s, GitHub Actions, and how they relate together for now. If you want to read about what k3s is, check out this article, or this one on GitHub Actions specifically.

Install Hugo

The first thing will be to download Hugo from their GitHub repository releases page. There are many options for various use cases and operating systems. We will use the hugo_extended version that has all that's necessary for development without having to install anything else. Download the latest version of hugo_extended for your operating system, expand it to a directory of your choice, and add that path to our PATH. Now, to test if everything is fine we execute this command, and you should see output like below:

% hugo version
Hugo Static Site Generator v0.74.3-DA0437B4/extended darwin/amd64 BuildDate: 2020-07-23T16:28:32Z

In my case I have the version v0.74.3 and as I'm on a Mac I use darwin/amd64. Your output may be different if you use another OS or the version number has changed.

Our first site

Once the installation of hugo is ready, we can create our first site, and we will do it with this command:

% hugo new site k3s-demo

Congratulations! Your new Hugo site is created in /hugo/k3s-demo.

Just a few more steps and you're ready to go:

1. Download a theme into the same-named folder.
   Choose a theme from https://themes.gohugo.io/ or
   create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
   with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".

Visit https://gohugo.io/ for quickstart guide and full documentation.

As the message says, we can go to the themes page and choose one that we like for our demo. I chose mixedpaper and we are going to install it by running the following command inside our project directory:

git submodule add https://github.com/wayjam/hugo-theme-mixedpaper.git k3s-demo/themes/mixedpaper

If it gives an error, it's most likely because your site is not in a git repository, which the command expects. Simply run git init to initialise a repository in your project's root directory. It is a good idea to create the corresponding GitHub repository now as well. After this we can enter the folder themes/mixedpaper. Inside will be a directory called exampleSite, under which we will find a file called config.toml. Copy this file to the root of our project:

k3s-demo $ cp themes/mixedpaper/exampleSite/config.toml .

Once this is done, standing at the root of our project we are going to run hugo in development mode like this:

% hugo serve

                   | EN
-------------------+-----
  Pages            |  6
  Paginator pages  |  0
  Non-page files   |  0
  Static files     |  6
  Processed images |  0
  Aliases          |  1
  Sitemaps         |  1
  Cleaned          |  0

Built in 44 ms
Watching for changes in /hugo/k3s-demo/{archetypes,content,data,layouts,static,themes}
Watching for config changes in /hugo/k3s-demo/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

If you visit http://localhost:1313/, you should see something like the following:

Hugo-Mixedpaper

So as not to complicate things for this guide, we are going to leave our site as is for now and proceed to the GitHub action. You will be able to add content once that is ready.

GitHub Actions

Now we are going to create everything necessary for our site to run in live Kubernetes. To start, we are going to need to create a repository for our site on GitHub.

Following this we are going to create this directory structure in the root of our site:

├── .github
│   └── workflows
│       └── main.yaml

After this we will create the secrets within our repository's settings on GitHub. You will need the following:

CIVO_TOKEN <-------- | Your Civo API token
DOCKER_EMAIL <------ | Your Docker Hub email
DOCKER_USERNAME <--- | Your Docker Hub username
DOCKER_TOKEN <------ | A token generated in Docker Hub's settings page

Once this is done, we are going to put the following content inside ./github/workflows/main.yaml, which will form the steps of our GitHub deployment action. It is set to run on changes to the main branch (labeled master in this case) by installing the Civo action that allows you to create a cluster. It the Dockerizes your Hugo site and applies that Docker container to the cluster.

name: Deploy-Site

on:
  push:
    branches:
    - master
  pull_request:
    branches: [master]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Install civo
      uses: civo/action-civo@v1.0.0
      with:
        token: ${{ secrets.CIVO_TOKEN }}

    - name: Create a k3s cluster
      run: >
        if [[ $(civo k3s show my-site -o custom -f ID) == "" ]]; then
            civo k3s create my-site -n 2 --wait
        fi

    - name: Make config folder
      run: mkdir ~/.kube

    - name: Save our cluster's authentication details
      run: >
        civo k3s config my-site --save
        --local-path ~/.kube/config -y

    - name: Ensure we can connect to the API
      run: >
        i=0;
        while [ $i -le 120 ]; do
          kubectl get nodes && break;
          ((i++));
          sleep 1;
        done

    - name: Authenticate our Kubernetes cluster to Docker Hub
      run: >
        if ! kubectl get secret regcred | grep "regcred"; then
          kubectl create secret docker-registry regcred
          --docker-email=${{secrets.DOCKER_EMAIL}}
          --docker-server=docker.io
          --docker-username=${{ secrets.DOCKER_USERNAME }}
          --docker-password=${{ secrets.DOCKER_TOKEN }}
        fi

    - name: Replace our cluster ID
      run: >
        sed -i'' -e "s/CLUSTER_ID/`civo k3s show my-site -o custom -f ID`/" k8s.yaml &&
        sed -i'' -e "s/CLUSTER_ID/`civo k3s show my-site -o custom -f ID`/" config.toml

    - uses: jakejarvis/hugo-build-action@master
      with:
        args: --minify --buildDrafts

    - name: Push to DockerHub
      uses: docker/build-push-action@v1
      with:
        username: ${{ secrets.DOCKER_USERNAME }}
        password: ${{ secrets.DOCKER_TOKEN }}
        repository: alejandrojnm/my-site
        tags: latest

    - name: Deploy our app to the cluster
      run: kubectl apply -f k8s.yaml

    - name: Wait for the deployment to be ready
      run: >
        i=0;
        while [ $i -le 120 ]; do
          kubectl rollout status deployment/my-site | grep "successfully rolled out" && break;
          ((i++));
          sleep 1;
        done

    - name: Update application
      run: kubectl patch deployment my-site -p "{\"spec\":{\"template\":{\"metadata\":{\"labels\":{\"date\":\"`date +'%s'`\"}}}}}"

In the above file you will only have to modify repository: alejandrojnm / my-site to include the repository you are going to use.

Now we are going to create the parts necessary to integrate everything. The first thing will be to create the Dockerfile file in the root of our project, with the following:

FROM nginx
COPY ./public /usr/share/nginx/html

This simply sets up a nginx web server to serve our site's public folder.

Following this we will create another file called k8s.yaml and inside we will put this:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-site
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-site
  template:
    metadata:
      labels:
        app: my-site
    spec:
      containers:
        - image: alejandrojnm/my-site:latest
          name: my-site
          imagePullPolicy: Always
      imagePullSecrets:
        - name: regcred
---
apiVersion: v1
kind: Service
metadata:
  name: my-site
  labels:
    app: my-site
spec:
  ports:
    - name: "my-site"
      port: 80
  selector:
    app: my-site
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: my-site-ingress
  annotations:
    kubernetes.io/ingress.class: "traefik"
  labels:
    app: my-site
spec:
  rules:
    - host: CLUSTER_ID.k8s.civo.com
      http:
        paths:
          - path: /
            backend:
              serviceName: my-site
              servicePort: 80

As with the earlier example, in this file you will also have to modify - image: alejandrojnm/my-site:latest to use the one that you put in the GitHub action. The other steps this deployment file takes are to create a service operating on port 80 and an ingress allowing routing to your deployed site.

Now our last step, remember the config.toml of our site that is at the root of our project? Well, we are going to modify it by replacing baseURL with this baseURL = "http://CLUSTER_ID.k8s.civo.com/".

Deploying

Now we only have to do commit and push to our repository and if everything went well, within a few minutes we will be able to see our Hugo site in the url CLUSTER_ID.k8s.civo.com. This site would get updated with new content, themes, or anything else you change in the repository, with each push to the main branch.

Next steps

Of course, this example is very simplistic. It assumes your site should exist in a Kubernetes cluster called "my-site", for one. It also makes the decision of the type and number of Civo Kubernetes nodes to deploy on your behalf. It also does not enable https, but that is best left to another guide.

You're free to play around with the values in the various yaml configuration files to get a deployment that suits your use case. Just make sure that if you are changing your cluster specifications you remove it from your Civo account. If you are simply changing configuration options, each time you commit the files and push to master the GitHub action will simply update rather than rebuild your cluster according to your specifications.

Let us know on Twitter or on the Civo Community Slack if you followed along, and where we can see your blog on the internet!