This article will detail how to build a Docker image.

Principle§

  1. Use Hugo to build the site and generate static files.
  2. Use Nginx as the server to handle requests.

Dockerfile§

Create a Dockerfile in the site root.

 1###############
 2# Build Stage #
 3###############
 4FROM klakegg/hugo:ext-ubuntu as builder
 5
 6WORKDIR /src
 7COPY . /src
 8
 9ARG HUGO_ENV=production
10ENV HUGO_ENV=${HUGO_ENV}
11
12# Base URL
13ARG HUGO_BASEURL=/
14ENV HUGO_BASEURL=${HUGO_BASEURL}
15
16# Module Proxy
17ARG HUGO_MODULE_PROXY=
18ENV HUGO_MODULE_PROXY=${HUGO_MODULE_PROXY}
19
20# NPM mirrors, such as https://registry.npmmirror.com
21ARG NPM_CONFIG_REGISTRY=
22ENV NPM_CONFIG_REGISTRY=${NPM_CONFIG_REGISTRY}
23
24# Install dependencies
25RUN npm install
26RUN npm install -g @fullhuman/postcss-purgecss rtlcss
27
28# Build site
29RUN hugo --minify --gc --enableGitInfo
30
31# Set the fallback 404 page if defaultContentLanguageInSubdir is enabled, please replace the `en` with your default language code.
32# RUN cp ./public/en/404.html ./public/404.html
33
34###############
35# Final Stage #
36###############
37FROM nginx
38COPY --from=builder /src/public /app
39COPY deploy/nginx/default.conf /etc/nginx/conf.d/default.conf
  • There are two stages to the build, a build stage and a release stage. The release stage contains only the generated static files, keeping the size of the Docker image as small as possible.
  • If you have defaultContentLanguageInSubdir enabled, please uncomment and modify it on demand.
  • The HUGO_BASEURL parameter is used to specify the baseURL of the site during the build, and is generally used when the baseURL is different from the configuration, so you can remove it yourself if you don’t need it.
  • HUGO_MODULE_PROXY and NPM_CONFIG_REGISTRY are optional build parameters that can be removed if not needed.

Nginx§

Create a deploy/nginx/default.conf in the site root:

 1server {
 2    listen       80;
 3    listen  [::]:80;
 4    server_name  localhost;
 5    
 6    root   /app;
 7
 8    location / {
 9        index  index.html index.htm;
10    }
11
12    location ~* ^/([^/]+) {
13        index  index.html index.htm;
14        error_page 404 = @error;
15    }
16
17    error_page 404 /404.html;
18    location @error {
19        try_files /$1/404.html /404.html =404;
20    }
21}

Build§

1$ docker build -t mysite \
2  --build-arg HUGO_BASEURL=https://example.com \
3  .
  • mysite: the image name.
  • HUGO_BASEURL：the baseURL.

For users located in China mainland, you need to specify HUGO_MODULE_PROXY and NPM_CONFIG_REGISTRY to build the image successfully and quickly:

1$ docker build -t mysite \
2  --build-arg HUGO_BASEURL=https://example.com \
3  --build-arg HUGO_MODULE_PROXY=https://goproxy.cn \
4  --build-arg NPM_CONFIG_REGISTRY=https://registry.npmmirror.com \
5  .

Deployment§

There are many ways to deploy Docker image, such as docker run, k8s, etc. This article will only explain docker run.

Run§

1$ docker run \
2  -p 2333:80 \
3  --name mysite \
4  --restart=always \
5  mysite

For local testing, you need to change the baseURL parameter or the HUGO_BASEURL build parameter, e.g. http://localhost:2333.

Stop§

1$ docker stop mysite

Start§

1$ docker start mysite

Remove§

1$ docker rm mysite