Public | Automated Build

Last pushed: a year ago
Short Description
Docker base image for static sites generation and serving using Hugo
Full Description

Hugo Docker Image

Docker image for building and serving hugo static websites (

Environment Variables

The docker image exposes the following environment variables to control the
behavior of the running container:

  • HUGO_SERVE To have the container act as a web server after generating
    the website - Default = false

  • HUGO_WATCH To watch for changes on the filesystem and regenerate -
    Default = false

  • HUGO_REFRESH_TIME The time interval to refresh the server or generated
    content (when value is -1 the script will exit after the first generation) -
    Default = -1

  • HUGO_SRC Location of the Hugo site to be generated - Default = .

  • HUGO_OUTPUT Location to place the generated site - Default = /public

  • HUGO_THEME Theme to use when generating the site - No default

  • HUGO_BASEURL URL used to access the site (For local testing use localhost) -
    No default

  • HUGO_BIND_ADDRESS Allows access to the served site from this address
    ( is open to all) - Default =

  • HUGO_PORT Port to server Hugo - Default = 1313

  • HUGO_BUILD_DRAFTS To enable generation of draft posts (should only be
    used locally) - Default = false

  • HUGO_BUILD_FUTURE The enable generation of future dated posts (should
    only be used locally) Default = false

  • HUGO_VERBOSE To enable verbose logging in Hugo - Default = false


There are two ways of executing the container:

  1. docker-compose: This is the easiest way
    of generating or running a site as the configuration can be placed as code
    without requiring you to remember the commands and options. See the section on
    docker-compose for more information about the configuration.

  2. Docker run: Is the common
    way of running a docker container. See the docker run section
    for the command details.

Building the Image

As above there are two options for building the container from scratch:

  1. docker-compose which can be executed
    simply be running the below command. Edit the image attribute in the
    docker-compose.yml file to name the created image.
docker-compose build
  1. Docker run is executed by
docker build -t <your_docker_username>/hugo:latest .

The image uses alpine as its
base is about 4.8 MB in size and the hugo docker image will be
approximately 22 MB in size once fully installed.

REPOSITORY                  TAG       IMAGE ID         CREATED         SIZE
mysocialobservations/hugo   0.15      ced02773a410     10 minutes ago  21.88 MB
mysocialobservations/hugo   0.17      44f0a693175e     15 minutes ago  22.81 MB
alpine                      latest    baa5d63471ea     6 weeks ago     4.803 MB

Multiple Hugo Version(s)

There are multiple versions of Hugo supported, each defined in their own folder
with the version number. Switch the relevant folder to build the version you
require and and execute the steps in the
Building the Image section.

Docker compose

Docker compose can both create a container to act as a webserver or generate
the static site as a once off.

Serving content

The docker-compose.yml file for creating a container that serves content is
below (See the Requirements section for more details):

version: '2'

    image: mysocialobservations/hugo
      - .:/src
      - ./public/:/public
      - HUGO_SERVE=true
      - HUGO_WATCH=true
      - HUGO_SRC=.
      - HUGO_OUTPUT=/public
      - HUGO_BASEURL=localhost
      - HUGO_PORT=1313
      - HUGO_THEME=hugo-theme-bleak
      - HUGO_BUILD_DRAFTS=true
      - HUGO_BUILD_FUTURE=true
      - HUGO_VERBOSE=true
    restart: always
      - '1313:1313'
    working_dir: /src
    command: /

and to execute this:

docker-compose up blog

Where you will see a log similar to:

Starting blog_blog_1
Attaching to blog_blog_1
blog_1      | HUGO_SERVE: true
blog_1      | HUGO_WATCH: true
blog_1      | HUGO_REFRESH_TIME: 5
blog_1      | HUGO_SRC: .
blog_1      | HUGO_OUTPUT: /public
blog_1      | HUGO_BASEURL: localhost
blog_1      | HUGO_BIND_ADDRESS:
blog_1      | HUGO_PORT: 1313
blog_1      | HUGO_THEME: hugo-theme-bleak
blog_1      | HUGO_BUILD_DRAFTS: true
blog_1      | HUGO_BUILD_FUTURE: true
blog_1      | HUGO_VERBOSE: true
blog_1      | Serving...
blog_1      | 1 of 1 draft rendered
blog_1      | 0 future content
blog_1      | 3 pages created
blog_1      | 8 paginator pages created
blog_1      | 2 categories created
blog_1      | 4 tags created
blog_1      | in 197 ms
blog_1      | Watching for changes in ./{data,content,layouts,static,themes}
blog_1      | Serving pages from /public
blog_1      | Web Server is available at http://localhost:1313/ 
(bind address
blog_1      | Press Ctrl+C to stop

To run the container in the background execute:

docker-compose up -d blog

And to see the state of the running container execute:

docker-compose ps

Name              Command   State    Ports
blog_blog_1       /   Up>1313/tcp

And to stop the running container:

docker-compose stop blog

Stopping blog_blog_1 ... done

Generating static website

The docker-compose.yml file can be configured to create a short lived
container that only generates content:

version: '2'

    image: mysocialobservations/hugo
      - .:/src
      - ./public/:/public
    working_dir: /src
    command: hugo

Where the output will be placed in the public folder.

You should see similar output to:

docker-compose up generate

Recreating blog_generate_1
Attaching to blog_generate_1
generate_1  | 0 of 1 draft rendered
generate_1  | 0 future content
generate_1  | 2 pages created
generate_1  | 8 paginator pages created
generate_1  | 4 tags created
generate_1  | 2 categories created
generate_1  | in 106 ms
blog_generate_1 exited with code 0

You can then view the site using the contents of the public directory and
deploy the folder to a webserver for external viewing.

Docker run

Similar to docker-compose you can create a container to act as a webserver
or generate the static site as a once off.

Serving content

Run the following command is equivalent to the docker-compose for serving

docker run \ 
 -e "HUGO_SERVE=true" \
 -e "HUGO_WATCH=true" \
 -e "HUGO_SRC=." \
 -e "HUGO_OUTPUT=/public" \
 -e "HUGO_BASEURL=localhost" \
 -e "HUGO_PORT=1313" \
 -e "HUGO_THEME=hugo-theme-bleak" \
 -e "HUGO_BUILD_DRAFTS=true" \
 -e "HUGO_BUILD_FUTURE=true" \
 -e "HUGO_VERBOSE=true" \
 -p 1313:1311 \
 -v $(pwd):/src \
 -v $(pwd)/public:/public \
 -w /src \
 mysocialobservations/hugo \

And to run this in detached or headless mode add -d to the command.

Generating static website

To run the equivalent docker command for generating the static website you can

docker run \
 -v $(pwd):/src \
 -v $(pwd)/public:/public \
 -w /src \
 mysocialobservations/hugo \

Which will place the generated files into the /public directory of the
container which is mapped to ./public on the host.


As the image and compose files take advantage of newer docker feature you may
face issues building the image using older versions of the below tools:

  • Docker: Tested using Docker version 1.12.1, build 6f9534c and may not work
    with lower versions of docker.
  • Docker-compose: Tested on docker-compose version 1.9.0, build 2585387. As
    the example docker-compose file makes use of the image attribute it requires
    version 1.7.x or higher.
  • Operating System: Currently tested against docker hosts running on Ubuntu
    16.04 LTS and CentOS 7 but should work on any host operating system capable of
    running the required versions of docker and docker-compose

Install required versions

If your operating system default installation does not include the required
versions you can manually install the latest version of both docker and
docker-compose. Be sure to uninstall any package manager versions to avoid

To install the latest version of docker execute:

curl -fsSL | sh

To install the latest version of docker compose:

curl -L$(uname -s)-$(uname -m)" > /usr/local/bin/docker-compose



Docker Pull Command