This Website

How this website is setup using Hugo and Github Actions

This website uses Hugo to process markdown test created on any machine and pushed to a git repository on github. This lets me update the website from anywhere with a text editor and an ssh client, and removes the need for me to run PHP on the server (for running Mediawiki or Wordpress, as I have in the past). In my opinion, PHP applications offer too many security holes.

This guide assumes three things,

You have a server running Debian linux
You have a Github account that allows Actions
You have a “local” computer you can create content on and can push to the github account.

These are the steps I took to tie all this together.

Step 1.

Install hugo on the server. Fairly self explanatory, for the purposes of this I am not using the extended version of hugo, so had no need to install npm or similar, so I don’t cover setting this up.

The version of hugo available from debian stable was a little tool old for my liking, so I built it from source as detailed here: build hugo from source. Building from source requires the Go languate to be installed, and a recent version at that, this can also be built from source if needed: Building Go from source

After the builds complete, I had Go installed at ~/src/goroot/bin

and hugo was copied from where I built it to /usr/local/bin so it was accessible from anywhere on the server.

Step 2.

For the purposes of this example, I’ll assume you wish all the the website work to be done in your home directory on the server, and you’ll wish to server the website from public_html on the server, giving a website URL like http://example.org/~debianuser/

If you want to do anything else, you should be able to modify the examples, once you have it running.

log into your server and make sure you’re in your home directory, we’ll create a couple of directories, one to serve the website from, public_html and one as a working directory web in this example:

  
  cd
  
  mkdir public_html
  
  mkdir web

Change to your web directory and create a new hugo site, you don’t have to do it this way, but it’s what worked for me. I create the base hugo site on the server, push to github and clone for update from my local machine.

  
  cd web
  
  hugo new site [sitename] #where [sitename] is the name of the new website.
  
  #we'll add a theme now. I'm using the hugo-ink theme.
  
  cd themes
  
  git clone https://github.com/knadh/hugo-ink.git
  
  cd ..
  
  echo theme = \"hugo-ink\" >> config.toml

It’s now a good time to get up git on this directory and get it pushed to your github repo.

We can test what we have so far by creating a new post on the server in hugo and starting up the built-in webserver in hugo to show it

  
  hugo new posts/my-first-post.md

Test the Hugo server.

  
  hugo server -D # D tells hugo to render draft articles too.

Hugo will reply something like

‘Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)’

If all is working, you should be able to visit the server ip or domain name and see your website post.

If all this works, you can now move on to step 3.

Step 3.

I want my server to receive a notification from github when I push a new article, or other website change to it, I want my server to run hugo on what it recieves and copy the HTML output to the root directory of the website.

I followed the instructions on the github self-hosted runners page

I use a deploy.yaml file to control what happens when the actions runner wakes up.


name: Deploy
on:
  push:
    branches:
      - main
jobs:
  build-deploy:
    runs-on: [self-hosted, webserver]
    steps:
    - name: Checkout
      uses: actions/checkout@v3
      with:
        submodules: 'recursive'

    - name: Build
      run:  hugo

    - name: Deploy
      run: chmod +x deploy.sh && ./deploy.sh

This calls my deploy.sh script that checks what machine it is being run on and copies the files into the correct place for that machine.



#!/bin/bash
hn=`hostname`
echo "Running on ... "
echo $hn

if [ $hn = "lovelace" ]; then
        cp -arv public/* $HOME/public_html/
elif [ $hn = "noether" ]; then
        cp -arv public/* /var/www/
else
        echo "Not a recognised machine"
fi

It’s not the most secure way to do this, in theory anyone that can access the git repository could edit the deploy script to be more malicious. Use two factor authentication and make the repository private.