I have been maintaining a git monorepo named docker_templates since sometime in 2023, and I recently added my 200th template (commit 7c112b7)! I thought back to 2015, when I started learning Docker and Docker Compose, and how transformative containers have been in the way I use my machines. There is something very satisfying about describing a runtime you want to work with and encapsulating everything you need to run an app or service the same way each time you run it, on any machine. In reality, there are some edge cases, but it’s a beautiful dream.

The structure of the docker_templates repository continues to evolve, but it’s also come a long way from where it started. I use this repository in some way almost every day. It is the heart of my homelab, and is where I keep references for pretty much every service I’ve stood up on one of my machines. I will now indulge my nostalgia by showing you how the repository has grown over time, how I use it, and share a few of my most useful/favorite containers.

The Beginning: Disparate Directories with Docker Compose Files

I learned to write Dockerfiles to containerize my Python programs, and quickly picked up Docker Compose so I could run things like a Postgres database or Redis message queue (for Python’s Celery scheduling library). Eventually, I started to find programs and apps I wanted to host myself, like a media server, document hosting, monitoring/alerting services, etc.

For years, whenever I wanted to try a new service, I would create a directory for it, write a docker-compose.yml file, and run it. I was hardcoding non-secret values in my Compose files for a long time (using a .env or environment variables to pass secrets to the template). Sometimes I would initialize a git repository and push the stack to Github, other times the directory would just sit on one of my machines wherever I originally put it. The mental overhead of deciding if the new service I wanted to try was worthy of initializing as a git repository, making sure my .gitignore would keep my .env file out of git history and ignore host volume mounts, and deciding where to put the code on my machine started to slow me down and made me hesitant to really invest time into the templates I was creating. I ended up with a lot of different repositories and realized this was not sustainable long-term.

The Monorepo

At some point in 2023, I decided to start a new git monorepo to store all of the services I ran in Docker Compose. I created my docker_templates repository, and one-by-one started copying Compose files I had written into the repository. Pulling everything into one place allowed me to do some cleanup, and made it much easier to start new templates. Whenever I wanted to run a new service, I would clone the repository into a path in my ~/git/ directory, name it after the service, and create the docker-compose.yml file alongside all my other templates in a branch named after the service. Each service existed in an immediate child of the templates/ directory, and over time that path became difficult to sort through.

This worked great for a while, but as I added more and more containers, and thought about all of the templates I planned to add in the future, I realized the structure of the templates/ directory would need to change, and the multiplicative git cloning would end up being a storage problem in the long term. I decided to overhaul the organization of templates in the repository, and write scripts to help me manage the complexity and initialize new templates in a standardized way.

Cookiecutter Templates

When I would start new service templates, I would usually go to a previous template and copy the docker-compose.yml and README.md files into the new path and rewrite them for the new service. I realized I wanted to standardize the way I initialized new template directories. I was familiar with Jinja2 templating from writing Python programs, and had used Cookiecutter in the past to create templated Python project repositories. So I created a standardized Docker Compose service template directory, with a common starting point for all future templates, and a Python script to guide the user through initializing a new template. I am definitely yada-yada-ing a lot of steps I took to get to this point, but after a few iterations, I settled on the template I have been using for the majority of the time this repository has existed.

Each new repository created from the Cookiecutter template starts with the same files:

• .docker-compose.template: An empty marker file for some of the maintenance scripts…I’ll explain more later.
• .env.example: I parameterize my compose.yml files, and provide an example .env file with the defaults for each service.
  • The user is instructed to copy .env.example to .env (which is ignored in the .gitignore for the whole repository) to configure the running stack.
• .gitignore: Template-local ignore pattern overrides.
• README.md: The new_template.py script prompts the user for a title, summary, and optional description, and populates the README file with the user’s inputs.
• compose.yml: The Python script generates a Docker Compose template file with the basic shape defined, so I can just start writing service definitions.

Path Markers

Once the template business was all sorted out, I decided to create subdirectories under the templates/ path that would serve as “categories.” I put my Postgres, Mariadb, Redis, and InnoDB containers under the database/ path, my Plex and Jellyfin servers under media/, Ntfy and Gotify containers under notifications/, and so on. Splitting things up this way made it easier to browse through the containers on the web, and helped to kept the stacks logically sorted by archetype.

In each “category” directory, I created an empty .category file marker. I used the .category and .docker-compose.template files to write scripts that managed some of the complexity in the repository. For example, the count_templates.py script finds all of the .docker-compose.template files in the repository and returns a count, which I use to update the templates count in the repository’s README.md. I wrote a Github workflow to run the script on a schedule, and if the count is different from what’s in the README.md, it updates the Templates:\s*\d+ pattern with the new count.

Repository Map

I also created a repository “map”, a README.md file that finds all of the .category markers and creates a file tree from a README.md Jinja template, and a script to update the map README when new categories are created. The update-repo-map.yml Github workflow also runs nightly to keep this file updated with the latest templates.

Repository Metadata

The scripts that update my README files also write data to the metadata/ directory. This can act as a sort of read-only API using cURL requests. For example, the repository map uses the categories.json file to populate the tree, and all .category and .docker-compose.template markers are in beacons.json. I started calling the marker files “beacons” at one point, and it just kind of stuck.

The metadata files are only really used for rendering README templates, but I have plans for things like a frontend webUI to explore the repository’s templates, and a Go CLI for downloading and using individual templates.

Git Sparse Checkouts

I mentioned earlier that I was cloning the whole repository each time I wanted to run a template I had in docker_templates. This quickly became a problem as the size of the repository grew. The repository is currently 10MB in size (mostly due to image files and some larger files in history that I’ll clean up at some point), so each time I cloned the repository, I added 10MB of disk usage.

I discovered git sparse checkouts when I searched for a solution to this problem. A sparse checkout is a git operation that allows you to checkout only a subset of the files in a repository. When I’m running a Docker Compose template, I don’t need to pull the src/img directory, with the .png I render in the main README.md; I can pull just the files in the Compose template I wish to run.

In practice, most of my sparse checkouts are ~5% of the total size of the repository, which is about the same amount of size they would take as separate git repositories. It adds a few steps to the initial checkout process, but it makes the clone a focused copy with only as much as I need to run.

As an example, if I want to run a Zabbix server container, I would run the following commands:

1
2
3
4
5
6
7
8

$> git clone --no-checkout https://github.com/redjax/docker_templates docker_zabbix
$> cd docker_zabbix
## Initialize sparse checkout
$> git sparse-checkout init --cone
## Tell git which paths to checkout
$> git sparse-checkout set templates/monitoring_alerting/docker_zabbix
## Checkout the main branch, or a working branch for the zabbix server
$> git checkout feat/some-zabbix-feature

This would create a directory named docker_zabbix/, which would have all of the files in the root path, and a single directory named templates/, with monitoring_alerting/docker_zabbix. All of the other containers still exist in the remote, but sparse checkouts let me focus on a single template.

Git Worktrees were not a thing when I started using sparse checkouts. An alternative to the sparse checkout method described above is cloning the whole docker_templates repository once, then creating worktrees for all of the services you want to run. A worktree exists in a separate path on the machine like a sparse clone would. They share the same git object database, meaning paths and objects are deduplicated, which saves space on the disk.

To create a Zabbix server container using a worktree, you would clone the whole repository once, cd into it, then create worktrees for each service you want to run. The limitation here is that each worktree checks out a branch, and only that worktree can use that branch. So, the original repository clone stays on the main branch, and each worktree must have its own branch, even if I’m not making any changes on that service.

1
2
3
4

$> git clone https://github.com/redjax/docker_templates
$> cd docker_templates
$> git worktree add -b feat/zabbix-server ../docker_zabbix
$> cd ../docker_zabbix

I have continued to use sparse checkouts because I often checkout a service and just run it on the main branch until I have updates or fixes to apply, and this flow does not work with worktrees.

How I Use It

I have a full clone of this repository on a few of my machines, which I don’t modify after cloning except to create new templates. When I want to try a new service, I cd into the local clone, create a branch for the new service, and run the new_template.py script, which prompts me for a template name, category, summary, and optional description. I usually add a link of some sort in the summary, i.e. a Github repository or documentation URL.

I commit the files as the initial starting point for that repository and push the branch up to git. Then I do a sparse clone and checkout the new service’s branch, and I get to work building the compose.yml and .env.example. I usually create host volume mounts in the git path, although a better practice would be storing Docker files in another path, like /opt/docker_data or something. The things we wished we learned sooner…

Eventually, when the template is in working condition, I merge the branch into main. As I make changes to the template, I create feat/ and fix/ branches, which also get merged into main. The idea/goal is to be running my services off the stable main branch as often as possible.

Favorite Containers

With some containers, I get them into working order, then bring the stack down and forget about it. I still like having the reference file in my repository, but I might not actively run the container. If it’s in the main branch, it means I got it running at one point and it’s ready to run again.

But there are some templates I am constantly running, or re-using on different machines.

• docker_pangolin: One of the most important services in my stack! Pangolin is my reverse HTTP proxy.
  • I have Pangolin running on a VPS I rent.
  • I route my domain name through Cloudflare, and have Cloudflare pointed at the VPS.
  • In Pangolin, I create subdomain routes to services I want to expose to the Internet, and route the traffic over a private tunnel.
• docker_adguard: I run an AdGuard Home container for ad blocking on my entire LAN.
  • My router uses the AdGuard container as its DNS server.
  • I create records for my important machines, so I can resolve machine-name.home anywhere on my network instead of remembering IP addresses.
• docker_netbird: I use Netbird to run a private network, similar to how many people use Tailscale.
  • I use access policies to allow or restrict traffic between devices, and to give my friends limited access to things like my media and game servers.
• docker_paperless-ngx: Paperless-ngx is an incredibly useful document management system.
  • I upload my receipts, work documents for things like benefits packages and employee handbooks, PDFs, and airline tickets.
  • Daily backups to local and offsite storage prevent data loss (and I’ve had to recover a few times; don’t neglect your backups!).
  • Full-text search lets me find things quickly, and the tagging system lets me sort documents, with tags like receipt, pets, house, vehicle, etc.
• docker_concourse_ci: I use Concourse CI for some of my homelab automation pipelines.
• docker_semaphore: Semaphore lets me run my Ansible roles and playbooks, as well as scheduled Bash scripts and Terraform from a convenient webUI.
• docker_gickup: Gickup is a useful utility for backing up and mirroring git repositories.
  • I keep a config file with all of my most important/valuable repositories, and Gickup runs on a Raspberry Pi, pulling my changes to a local drive and mirroring some to a self-hosted Git instance.
• database: A collection of database templates.
  • I frequently use Postgres and Redis in my homelab, and I use InfluxDB for some of my time-series data like weather readings.
• docker_linkwarden: Linkwarden is a bookmarking/read-it-later app.
  • I imported all of my browser bookmarks when I set it up initially, and I frequently save new links I come across on the web.
  • I can export Linkwarden’s saved links as a bookmarks.html file to synchronize back to my browser.
• docker_forgejo: Forgejo is a self-hosted Git forge, reminiscent of 2015-2018 Github.
  • The Forgejo Actions platform is semi-compatible with Github actions, and Forgejo’s pipelines are very similar in syntax.
  • I host a private/local-only Git forge for some of my more sensitive repositories that I do not want to expose to the Internet.
• docker_opengist: I am a big fan of Github Gists, and discovered OpenGist, which is basically the self-hosted version.
  • I put a lot of code snippets, scripts, and reference files here, and occasionally I will expand a gist into an Obsidian note, or a post on this blog!
• dav: I self-host my contacts and calendars, and synchronize them with my email client.
  • I primarily use Radicale, but have recently been test driving Davis and am liking it a lot.
• games: I host a bunch of game servers for my friends and me. We connect over a private network I host to play.
• monitoring_alerting: I have tried many different monitoring/alerting solutions, and have kept a template for each one in this path.
  • I used Zabbix for a while, but more recently I have used Beszel for server metric monitoring, Uptime Kuma for uptime checks, happyDomain to track and monitor my domains and DNS records, and NtopNG for local network monitoring.
  • I run Uptime Kuma from a VPS so it can watch my homelab for outages.
• docker_ntfy/docker_gotify: My own self-hosted push notification servers.
  • Ntfy and Gotify work very similarly, and I have been test driving both for a while.
  • I can’t decide which one I prefer, and I don’t see much harm in using both.
  • I’ve recently added Apprise into the mix, which lets me send notifications to both services.

Git filter-repo plugin

Install the git-filter-repo plugin for Git with Python:

1

pip install git-filter-repo

This plugin is required to run the git filter-repo command. It is ok to install this using “system Python.”

If you are running Linux, you can install it with apt install -y git-filter-repo (or whatever package manager your distribution uses, i.e. dnf for RedHat/Fedora).

Steps

Clone the repository that has the history you want to rewrite using the --bare flag:

1

git clone --bare git@github.com:user/repo.git

Run the following command to replace all instances of the old/wrong name & email with a different Git user:

1
2
3
4
5
6
7
8

git filter-branch --env-filter '
if [ "$GIT_COMMITTER_NAME" = "Old Name" ] && [ "$GIT_COMMITTER_EMAIL" = "old.email@example.com" ]; then
    GIT_COMMITTER_NAME="New Name"
    GIT_COMMITTER_EMAIL="new.email@example.com"
    GIT_AUTHOR_NAME="New Name"
    GIT_AUTHOR_EMAIL="new.email@example.com"
fi
' --tag-name-filter cat -- --branches --tags

Clean the reflog and run Git garbage collection to remove any cached history with the old Git user:

1
2

git reflog expire --expire=now --all
git gc --prune=now

Finally, force push the changes back to the remote:

1
2

git push --force --all
git push --force --tags

Verify the rewrite succeeded by cloning the repository to a new path and search the log for the old user:

1
2
3
4

mkdir ~/tmp
git clone git@github.com:user/repo.git ~/tmp/repo
cd ~/tmp/repo
git log --author="Old Name"

You should not see any results; if you do, look back through the history of your commands to see if there were any errors during the process.

Bash script

On a Linux or Mac system, you can use this Bash script to automate the steps above. Run the script with --help to see the usage menu.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231

#!/usr/bin/env bash
set -euo pipefail

## Find a Python interpreter for pip installs
PYTHON_BIN=""
for bin in python3 python py py3 python; do
  if command -v "$bin" >/dev/null 2>&1; then
    PYTHON_BIN=$bin
    break
  fi
done

## Ensure git-filter-repo is installed (try uv first, then pip)
if ! command -v git-filter-repo >/dev/null 2>&1; then
  echo "git-filter-repo not found."

  ## Install with uv, if available
  if command -v uv >/dev/null 2>&1; then
    echo "uv found. Installing git-filter-repo as a tool..."
    uv tool install git-filter-repo
    export PATH="$HOME/.local/bin:$PATH"
  fi

  if [[ -z "$PYTHON_BIN" ]]; then
    echo "No Python interpreter found. Please install Python or uv."
    exit 1
  fi

  ## Fallback to Python
  echo "Using $PYTHON_BIN to install git-filter-repo via pip..."
  "$PYTHON_BIN" -m pip install --user git-filter-repo
  export PATH="$HOME/.local/bin:$PATH"
fi

## Test git-filter-repo was installed correctly
if ! command -v git-filter-repo >/dev/null 2>&1; then
  echo "git-filter-repo still not found after installation attempts."
  exit 1
fi

## Function to print help menu/usage
usage() {
  echo ""
  echo "Usage: $0 [--force] \\"
  echo "          --repo-url git@github.com:user/repo.git \\"
  echo "          --source-email 'old.email@example.com' \\"
  echo "          --target-email 'new.email@example.com' \\"
  echo "          [--source-name 'Old Name'] \\"
  echo "          [--target-name 'New Name']"
  echo ""

  exit 1
}

## Default vars
REPO_URL=""
SRC_EMAIL=""
TGT_EMAIL=""
SRC_NAME=""
TGT_NAME=""
FORCE_PUSH=""

## Parse arguments
while [[ $# -gt 0 ]]; do
  case $1 in
  --repo-url)
    REPO_URL="$2"
    shift 2
    ;;
  --source-email)
    SRC_EMAIL="$2"
    shift 2
    ;;
  --target-email)
    TGT_EMAIL="$2"
    shift 2
    ;;
  --source-name)
    SRC_NAME="$2"
    shift 2
    ;;
  --target-name)
    TGT_NAME="$2"
    shift 2
    ;;
  --force)
    FORCE_PUSH=1
    shift
    ;;
  -h | --help)
    usage
    ;;
  *)
    echo "Invalid argument: $1"
    usage
    ;;
  esac
done

if [[ -z "$REPO_URL" || -z "$SRC_EMAIL" || -z "$TGT_EMAIL" ]]; then
  echo "Missing required arguments."
  usage
fi

echo "Repo URL: $REPO_URL"
echo "Replacing source email <$SRC_EMAIL> with target email <$TGT_EMAIL>"

if [[ -n "$SRC_NAME" ]]; then
  echo "Source name: $SRC_NAME"
fi
if [[ -n "$TGT_NAME" ]]; then
  echo "Target name: $TGT_NAME"
fi

## Create temporary directory to clone repo into
TMP_DIR=$(mktemp -d)
echo "Mirror cloning repository into temporary directory: $TMP_DIR"
git clone --mirror "$REPO_URL" "$TMP_DIR/repo"
cd "$TMP_DIR/repo"

echo "Rewriting commit history emails with git-filter-repo..."
## Read history with source username/email, replace with target
COMMIT_CALLBACK="
if commit.author_email.decode('utf-8') == '$SRC_EMAIL':
    commit.author_email = b'$TGT_EMAIL'
"
if [[ -n "$TGT_NAME" ]]; then
    COMMIT_CALLBACK+="
    commit.author_name = b'$TGT_NAME'
"
fi

COMMIT_CALLBACK+="
if commit.committer_email.decode('utf-8') == '$SRC_EMAIL':
    commit.committer_email = b'$TGT_EMAIL'
"
if [[ -n "$TGT_NAME" ]]; then
    COMMIT_CALLBACK+="
    commit.committer_name = b'$TGT_NAME'
"
fi

echo "Generated callback:"
echo "$COMMIT_CALLBACK"

## Rewrite history
git filter-repo --force --commit-callback "$COMMIT_CALLBACK"

echo "git filter-repo completed successfully"
echo "Verifying first few commits after rewrite..."
git log --all --pretty=format:"%h %ad %an <%ae>" --date=iso -5

echo "Removing backup refs..."
##  Remove all refs with old data
git for-each-ref --format='%(refname)' refs/original | xargs -r git update-ref -d
git for-each-ref --format='%(refname)' refs/backup | xargs -r git update-ref -d

echo "Expiring reflogs and pruning unreachable objects..."
## Expire old data locally before pushing
git reflog expire --expire=now --all
git gc --prune=now --aggressive

echo "Verifying no lingering commits with source email anywhere..."

## Get list of commits with source email
SOURCE_COMMITS=$(git for-each-ref --format='%(refname)' | while read -r ref; do
  git log "$ref" --pretty=format:"%H%x09%ad%x09%an%x09%ae%x09%cN%x09%cE" --date=iso |
    awk -v src_email="$SRC_EMAIL" '
        $4 == src_email || $6 == src_email {
            print FILENAME "\t" $0
        }' FILENAME="$ref"
done)

## If any commits remain with source email, exit
if [[ -n "$SOURCE_COMMITS" ]]; then
  echo ""
  echo "[ERROR] Some commits still contain the source email <$SRC_EMAIL>:"
  echo ""
  echo -e "Ref\tCommit\tDate\tAuthorName\tAuthorEmail\tCommitterName\tCommitterEmail"
  echo "$SOURCE_COMMITS"
  echo ""
  echo "Aborting push."

  exit 2
fi

echo "Removing local refs under refs/merge-requests/ to avoid push errors..."
## Remove all refs under refs/merge-requests/
git for-each-ref --format='%(refname)' refs/merge-requests | xargs -r -n 1 git update-ref -d || true

echo "Adding remote origin after filter-repo cleanup..."
## Re-add origin (git-filter-repo removes it)
git remote add origin "$REPO_URL"

echo "Pushing all branches and tags to origin forcibly..."
## Push rewritten histories back up
if [[ -n "${FORCE_PUSH:-}" ]]; then
  if ! git push origin --force --all; then
    echo ""
    echo "[ERROR] Failed to push rewritten commits to origin."

    exit 1
  fi

  if ! git push origin --force --tags; then
    echo ""
    echo "[ERROR] Failed to push rewritten commits to origin."

    exit 1
  fi

else
  if ! git push origin --force --all; then
    echo ""
    echo "[ERROR] Failed to push rewritten commits to origin."

    exit 1
  fi

  if ! git push origin --force --tags; then
    echo ""
    echo "[ERROR] Failed to push rewritten commits to origin."

    exit 1
  fi
fi

echo "Successfully rewrote all commits and pushed to remote."
echo "Temporary repo location: $TMP_DIR/repo"

exit 0

Static sites are perfect for many different kinds of websites, from personal blogs like this site to product sites (i.e. Brave browser’s website) to an organization’s home page (i.e. the LetsEncrypt project’s site) to documentation sites (i.e. DigitalOcean’s documentation). With a static site generator, you do not have to deal with web code like HTML or Javascript, but you still have the option of creating your own custom themes if that appeals to you.

When Hugo renders your source code into a website, it outputs everything you need to start serving the site to a public/ directory, allowing you to host the page in Docker, or on a VPS you control, or with a service like Netlify. You could even host your site on a Raspberry Pi you own (although I would recommend looking into running the site in a Docker container, instead of a Canonical Snap). Anywhere that can serve HTML should be able to serve your compiled Hugo website.

This blog will run through the basic steps to initialize a Hugo project, host it on Github, and setup hosting with Netlify.

Requirements

• Hugo
  • You should also pick a Hugo theme, i.e. PaperMod
• Go (optional)
  • You can add themes as a Hugo module instead of using Git submodules.
• Git
• Github account
• Netlify account

Initialize Hugo repository

There are different ways of structuring the repository, like putting the site’s content in a src/ directory or storing multiple Hugo sites in a single monorepo. This guide assumes you follow the default steps for initializing a Hugo project, where all source code is in the “root” of the repository.

First, cd to a path where you want to initialize your Hugo site, i.e. ~/git or just ~/ and initialize the site with:

1

hugo new site <your-blog-name>

Replace <your-blog-name> above with the name of your blog. The documentation uses quickstart as an example. You can name the site whatever you want, and can change it later by editing the hugo.toml/hugo.yml file the hugo new site command creates. When you run the Hugo command, you will see output with some first steps and instructions for editing the hugo.toml to change the site’s configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

$> hugo new site your-site-name
Congratulations! Your new Hugo site was created in /home/username/git/your-site-name.

Just a few more steps...

1. Change the current directory to /home/username/git/your-site-name.
2. Create or install a theme:
   - Create a new theme with the command "hugo new theme <THEMENAME>"
   - Or, install a theme from https://themes.gohugo.io/
3. Edit hugo.toml, setting the "theme" property to the theme name.
4. Create new content with the command "hugo new content <SECTIONNAME>/<FILENAME>.<FORMAT>".
5. Start the embedded web server with the command "hugo server --buildDrafts".

See documentation at https://gohugo.io/.

This is an example of the files hugo new site creates:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

your-site-name/
├── themes
├── static
├── layouts
├── i18n
├── hugo.toml
├── data
├── content
├── assets
└── archetypes
    └── default.md

Since this blog post is not meant to be an in-depth tutorial of how to build a website with Hugo, we will not go into detail on every single file and folder this command creates, but some important things to know are:

• The themes/ directory is where you store themes added as Git submodules.
  • This guide assumes you are using Hugo modules to install themes, instead of the old Git submodule way, so you will not need to interact with the themes/ directory.
  • This is also where you would store a custom theme, if you wanted to create your own Hugo theme for your site.
• The static/ directory is where you would store static assets for your site, including images and a favicon.ico for the site.
  • Although counter-intuitive, it is generally considered best practice to include the binaries for your static resources in the Git repository.
  • Save your favicon.ico to static/favicon.ico (if you have one), and any images you use in your posts in static/img (this directory doesn’t exist by default, you have to create it).
• The layouts/ directory is where you can create Hugo templates for finer-grained control of how content is displayed on your site.

The hugo.toml file is the main configuration file for your site. If you prefer YAML, you can copy the contents of hugo.toml into convertsimple.com, delete or rename hugo.toml to hugo.yaml/hugo.yml, and paste the converted configuration into the YAML file. Hugo will detect a file named hugo.yml or hugo.toml wherever you run hugo commands from. This guide assumes you are using YAML for your configuration.

1

hugo new site site-name --format yaml

Convert Site to Hugo Module

Next, initialize your site as a Hugo module:

1

hugo mod init github.com/username/your-site-name

After running this, you will see a go.mod file. This allows Go to mannage your site so you can install themes like they are Go packages. For example, to install the PaperMod theme by editing your hugo.yml file and adding the following block of code:

1
2
3

module:
  imports:
    - path: github.com/adityatelange/hugo-PaperMod

The full hugo.yml should now look like this:

1
2
3
4
5
6
7

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

module:
  imports:
    - path: github.com/adityatelange/hugo-PaperMod

Run Local Hugo Development Server

Now you can test running the server with hugo serve, which will compile the site and start serving it at http://localhost:1313/ by default. To change the host address, i.e. to access it from another machine on the network, use --bind 0.0.0.0, and to change the port use -p <port>. This is Hugo’s development server. As you edit files, the server will ‘hot reload,’ re-compiling the Markdown you write and restarting the server.

Hugo does this very quickly. Each page takes mere milliseconds to render, even those with images or a lot of text, and it caches between rebuilds, only re-rendering the new content. This leads to a pleasant “change something and see it instantly” writing experience.

If you start the server with -D, Hugo will also render your drafts in the development server.

Git Repository Setup

Run git init -b main in your Hugo site’s directory to initialize a new Git repository. Before committing any code, add a .gitignore that ignores Hugo’s public/ and resources/ directories that it creates when you run the development server:

1
2

/public/
/resources/

Then, do your initial commit:

1
2

git add *
git commit -m "Initial commit"

Create a repository on Github for your Hugo site. This should match the URL you used when you create the Hugo module with hugo mod init github.com/user/your-site-name. Add the remote to your local repository:

1

git remote set origin git@github.com:username/your-site-name.git

And push your code with git push -u origin main.

Netlify Setup

Create an account on Netlify. During the setup process, you will be asked to create a project. Allow Netlify to integrate with your Github and find the repository with your Hugo site. If you already have a Netlify site, add a new project and use “Import an existing project” and find your Hugo repository.

When you are prompted to input build settings like the base directory/package directory, the build command, the publish directory, etc, leave all of these blank. You can optionally leave the functions directory as netlify/functions. If you set values here, the site will fail to build because the hugo.yml interferes with these settings. Do your site configuration in hugo.yml, not Netlify.

When asked which branch to trigger Netlify deploys on, you have a decision to make: do you want your site to deploy every single time you open a PR to the main branch, including times where you are doing small cleanup chores like updating the .gitignore, or setting up a new pipeline? Or do you want to have more control over deploys, i.e. only when merging into a branch named netlify?

I chose the latter, and created a netlify branch, then configured Netlify to deploy from the netlify branch instead of main. I also turned off deployment previews, so any PR into netlify will trigger a deploy.

netlify.toml Config

After finishing the setup, create a netlify.toml file in the root of your Hugo repository :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

[build.environment]
HUGO_BASEURL = "https://netlify-project-name.netlify.app"
HUGO_VERSION = "0.152.2"
HUGO_ENV = "production"
NODE_VERSION = "24"
HUGO_ENABLEGITINFO = "true"

[build]
command = "hugo --gc --minify"
publish = "public"

This file tells Netlify how to build your Hugo site. Commit it to git with git add * && git commit -m "Add netlify config" and push to main with git push. Even better, create a new branch before adding/committing your code, i.e. git switch -c feat/netlify-setup, then add the files and commit message. When you push, use git push -u origin feat/netlify-setup. Merge the branch into the main branch in Github.

Example Production Hugo Dockerfile

If you plan to host your Hugo site yourself, you can set up a Dockerfile to build your site and serve it behind a proxy like Caddy or NGINX.

You can use a multi-stage Docker build to have a smaller final image that only has your rendered HTML and the Caddy server to serve it:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

FROM hugomods/hugo:exts AS builder

WORKDIR /src

## Copy Hugo site files & config
COPY archetypes/ archetypes/
COPY assets/ assets/
COPY content/ content/
COPY layouts/ layouts/
COPY static/ static/
COPY hugo.yml go.mod go.sum .hugo_build.lock ./

ARG HUGO_BASEURL=http://localhost/

RUN hugo \
  --minify \
  --gc \
  --baseURL="${HUGO_BASEURL}" \
  --destination /output/public

FROM caddy:alpine

COPY --from=builder /output/public /usr/share/caddy

COPY ./Caddyfile /etc/caddy/Caddyfile

EXPOSE 80 443

CMD ["caddy", "run", "--config", "/etc/caddy/Caddyfile"]

Create a Caddyfile the container will use to configure the Caddy server:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  # debug
  email {$CADDY_EMAIL}
}

{$CADDY_SITE_ADDRESS} {
  root * /usr/share/caddy
  file_server
  encode gzip

  header {
    X-Content-Type-Options nosniff
    X-Frame-Options DENY
  }
}

When you build the container, you will need to set environment variables for CADDY_EMAIL (for automated LetsEncrypt SSL certificates) and CADDY_SITE_ADDRESS (for handling connections coming to the Caddy URL). The 2 env vars are “build arguments”, which you can inject in your docker build command using --build-arg ARG_NAME=value. For example, to build this Dockerfile:

1

docker build --build-arg CADDY_EMAIL="youremail@address.com" --build-arg CADDY_SITE_ADDRESS="myblog.com" .

Check Links with Lychee

Lychee is a fast link checker you can use to check your site for broken links. You can install it locally and point it at your live site, or you can run it against the public/ directory after Hugo builds to check your links before deploying.

Lychee’s syntax is simple:

1
2
3
4
5

## Check links on your live site
lychee https://your-site-name.com

## Check links in the public/ directory after a Hugo build
lychee public/

As a Github action:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

---
name: "Test Blog Links"

on:
  ## Allow manual runs
  workflow_dispatch:
  
  ## Every 6 hours
  schedule:
    - cron: "0 */6 * * *"

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - name: Test live site links
        uses: lycheeverse/lychee-action@v1
        with:
          args: >-
            --base-verification false 
            --no-progress 
            "${{ vars.HUGO_BASEURL }}"/*

Or in a full pipeline that builds the site and then tests the public/ directory (this is useful to do before deploying):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

---
name: "PR checks"

on:
  pull_request:
    branches: [netlify]
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

env:
  HUGO_VERSION: "0.154.3"

jobs:
  test:
    name: Build & test Hugo site
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Vale prose linting
        uses: errata-ai/vale-action@v2.1.1
        with:
          files: '["content/**.{md}"]'

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: ${{ env.HUGO_VERSION }}
          extended: true

      - name: Build site
        run: hugo --gc --minify

      - name: Check links with Lychee
        uses: lycheeverse/lychee-action@v1
        with:
          args: "public/**/*.html --base ."
          fail: false

Closing

Building a blog with Hugo is fun, and relatively quick and easy to get up and running. You can build a complex site for your product, or a simple blog you update a couple times a year, all with the same tooling. The minimal amount of configuration you need to get started lends itself to quick development, while still allowing you to build up a more complex configuration over time. Hugo modules make it even easier to install themes and site extensions, and the ability to host the site anywhere that can serve static web files gives you a ton of flexibility to where you put the site online.

This guide did not go in-depth on configuring and customizing Hugo, nor did it walk through creating content for the site. The Hugo quickstart guide will do a better job of walking you through building your first blog, and I highly recommend keeping this site open and using the search bar at the top as you’re learning to find new ways of using Hugo.