Getting Hugo Up and Running With a Fresh Docker Install

I’m a big fan of Docker as a way to isolate services and avoid the need to install dependencies on the base operating system. There turned out to be a few nuances getting Hugo up and running.

Docker will not start without a site config file

Create a basic config file (we can delete this later…). Thanks no D in rogers!

baseURL = 'http://example.org/'
languageCode = 'en-us'
title = 'My New Hugo Site'

Create a new site with docker.

docker run --rm -it -v $(pwd):/src klakegg/hugo:0.101.0-ext-alpine hugo new site story-examplesite

Create a docker compose file, the hugo server must be given the folder to start in:

version: '3.7'

services:
  hugo:
    container_name: "hugo"
    restart: unless-stopped
    image: klakegg/hugo:0.101.0-ext-ubuntu
    command: server --source story-examplesite
    volumes:
      - "./:/src"
    ports:
      - '1313:1313'

Start hugo

docker compose up -d
docker exec -it hugo /bin/bash

Creating a theme from scratch

Pedro Lopez provides a great tutorial . I won’t duplicate it here, I found it an excellent way to build an understanding of how Hugo works under the covers.

Debugging

One thing I learnt from Drupal many years ago was the importance of being able to see variable values for debugging. The Hugo documentation suggests using printf statements such as

{{ printf "%##v" $.Site }}

but I didn’t find these very helpful, especially if you want to see the values within the dot object

{{ printf "%##v" . }}

I am currently using Hugo ‘debugprint’ which provides a debugging partial:

{{ partial "debugprint.html" . }}

To install:

1. clone the git repo to your-site/themes/hugo-debugprint directory:

cd your-site/themes/hugo-debugprint
git clone https://github.com/kaushalmodi/hugo-debugprint.git

2. Add ‘hugo-debugprint’ as the left-most element of the theme list variable in your site’s or theme’s config.toml. Example:

theme = ["hugo-debugprint", "my-theme"]

Overriding a theme

I started changing some theme files but on further research, I learnt this isn’t the right approach. Instead of directly changing the theme file, it’s better to override the original template with a new file.

To override:

/themes/themename/layouts/_default/single.html

create:

/layouts/_default/single.html

Hosting with docker apache and traefik

Spinning up a docker apache server on a remote server with Digital Ocean turned out to be really quick. I use rsync to move the content from a local hugo instance to this remote server for hosting. I’ll post the traefik config in a separate post.

version: '3.9'
services:
  apache:
    image: httpd:latest
    container_name: apache-hugo-deploy
    networks:
      - proxy
    volumes:
      - /docker/hugo/site-name/public:/usr/local/apache2/htdocs
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.apache-hugo-web.rule=Host(`www.domain-name.com`)"
      - "traefik.http.routers.apache-hugo-web.entrypoints=websecure"
      - "traefik.docker.network=proxy"

networks:
  proxy:
   external: true