Hugo Docker Images

This article describes the up-to-date Hugo docker images, and offer some examples show how to develop and deploy your sites with the images.

How to Build Latest Images?

We set up an automated workflow for checking and building latest Hugo images, which can be triggered by:

1. Cron job which runs every 30 mins.
2. Commenting on the issue.

Images

The images will be pushed to both of Docker Hub and GitHub Container Registry.

We’ve renamed razonyang/hugo to hugomods/hugo, the former won’t be got updated anymore, please use hugomods/hugo instead.

Image Tags

Tag	Size	Hugo	Extended	Go	Node	NPM	Git
latest, <version>		✅	✅	✅	✅	✅	✅
base, base-<version>		✅	✅	❌	❌	❌	❌
git, git-<version>		✅	✅	❌	❌	❌	✅
go, go-<version>		✅	✅	✅	❌	❌	❌
go-git, go-git-<version>		✅	✅	✅	❌	❌	✅
node, node-<version>		✅	✅	❌	✅	✅	❌
node-git, node-git-<version>		✅	✅	❌	✅	✅	✅
node-lts, node-lts-<version>		✅	✅	❌	✅	✅	❌
exts, exts-<version>		✅	✅	✅	✅	✅	✅
reg, reg-<version>		✅	❌	✅	✅	✅	✅
reg-base, reg-base-<version>		✅	❌	❌	❌	❌	❌
reg-git, reg-git-<version>		✅	❌	❌	❌	❌	✅
reg-go, reg-go-<version>		✅	❌	✅	❌	❌	❌
reg-go-git, reg-go-git-<version>		✅	❌	✅	❌	❌	✅
reg-node, reg-node-<version>		✅	❌	❌	✅	✅	❌
reg-node-git, reg-node-git-<version>		✅	❌	❌	✅	✅	✅
reg-node-lts, reg-node-lts-<version>		✅	❌	❌	✅	✅	❌
reg-exts, reg-exts-<version>		✅	❌	✅	✅	✅	✅
nginx		❌	❌	❌	❌	❌	❌

• <version>: the placeholder for Hugo version, i.e. 0.112.7.
• reg: represents the regular/standard Hugo version.
• exts: the exts includes not only the tools listed above, but also Embedded Dart Sass, PostCSS CLI, Autoprefixer, PurgeCSS and RTLCSS.
• node-lts: represents the LTS (long time support) version of Node.js.

Image Tags Architectures

All image tags except exts* support linux/amd64 and linux/arm64.

Development

We provides a walkthrough about using Hugo Docker images to develop our themes or sites.

Pick Up the Right Image Tag

Firstly, compare and pick up the Docker images. Let’s take hugomods/hugo image as an example.

1docker pull hugomods/hugo

Change Current Working Directory

Change current working directory to your project root.

1cd my-site

Install Dependencies (Optional)

Skip this step if your site/theme doesn’t require it.

You may want to install the dependencies before running Hugo server, such as install dependencies via npm.

1docker run \
2  -v ${PWD}:/src \
3  hugomods/hugo \
4  npm i

• -v ${PWD}:/src mounting current working directory as site source inside Docker container.

Start Hugo Server

1docker run -p 1313:1313 \
2  -v ${PWD}:/src \
3  hugomods/hugo \
4  hugo server --bind 0.0.0.0

• -p port:port mapping from host machine port to container port.

Note that --bind 0.0.0.0 is required.

Using another port than 1313, such as 8080.

1docker run -p 8080:8080 \
2  -v ${PWD}:/src \
3  hugomods/hugo \
4  hugo server --bind 0.0.0.0 -p 8080

Deployment

The following example uses Nginx (hugomods/hugo:nginx) as web server to serve Hugo generated static files.

Create Dockerfile

Firstly, create the Dockerfile file on your site root.

 1#####################################################################
 2#                            Build Stage                            #
 3#####################################################################
 4FROM hugomods/hugo:exts as builder
 5# Base URL
 6ARG HUGO_BASEURL=
 7ENV HUGO_BASEURL=${HUGO_BASEURL}
 8# Build site
 9COPY . /src
10RUN hugo --minify --gc --enableGitInfo
11# Set the fallback 404 page if defaultContentLanguageInSubdir is enabled, please replace the `en` with your default language code.
12# RUN cp ./public/en/404.html ./public/404.html
13
14#####################################################################
15#                            Final Stage                            #
16#####################################################################
17FROM hugomods/hugo:nginx
18# Copy the generated files to keep the image as small as possible.
19COPY --from=builder /src/public /site

Test Built Image

1docker build \
2  -t user/my-site:test \
3  --build-arg HUGO_BASEURL=http://localhost:8080 \
4  .

1docker run -p 8080:80 user/my-site:test

• -t specifies the image name and tag.
• --build-arg HUGO_BASEURL=http://localhost:8080 overrides the baseURL.

Now the built site can be previewed on http://localhost:8080/.

Build and Deploy Image

It’s time to build the production image if test passing.

1docker build -t user/my-site .

Now you can push your images to container registry, and then deploy it to server, K8s cluster, DigitalOcean App Platform or something else.