Establishing a reliable and predictable Hugo development environment is crucial for efficient project workflows. Docker makes it straightforward to create a cross-platform, repeatable, and customizable setup, ensuring your environment remains consistent regardless of your operating system. In this post, we’ll demonstrate how to set up a robust Hugo development environment using Docker, making it easy to get started and maintain your projects across different machines.
Prerequisites #
docker
installed locally- installs
runc
containerd
- installs
docker-compose
(optional)
Install Docker #
- Installing packages on Arch:
sudo pacman -S docker
- Installing packages on Ubuntu/Debian:
sudo apt-get install docker
Info! Additional install information can be referenced here.
Configure Environment #
- Add your user to the docker group:
sudo usermod -aG docker $(whoami)
Info! This will allow a non-root user to issue
docker
commands. A reboot may required on some systems.
- Start the docker service:
systemctl start docker
- Verify docker installation:
docker version
Launch Website #
- Navigate to the root folder of my-hugo-site:
cd my-hugo-site
- Run
docker
to serve my-hugo-site locally:
docker run --rm \
-p 1313:1313 \
--name my-hugo-site \
-v ${PWD}:/src \
-v ${HOME}/hugo_cache:/tmp/hugo_cache \
hugomods/hugo:go-git-non-root \
server
Info! On first execution
docker
will pull the hugomods.com image docker.io/hugomods/hugo:go-git-non-root
. Images with different feature sets can be found here.
- Verify the site is available:
My New Hugo Site: http://localhost:1313/
You now have a flexible and easily controllable development environment that can be configured to meet your specific needs. For more information on customization options, see the Enhancements section.
Enhancements (Optional) #
Install Docker Compose #
- Installing packages on Arch:
sudo pacman -S docker-compose
- Installing packages on Ubuntu/Debian:
sudo apt-get install docker-compose
- Verify docker-compose installation:
docker compose version
Launch Website Using docker-compose
#
- Create
docker-compose.yml
in my-hugo-site working directory:
cd my-hugo-site
name: my-hugo-site
services:
server:
image: hugomods/hugo:go-git-non-root
command: server -D
volumes:
- ./:/src # maps current working directory /src
- ~/hugo_cache:/tmp/hugo_cache
ports:
- 1313:1313
docker compose up server
- Verify the site is available.
Launch Website Using a Specific Hugo Version #
- Assuming completion of
docker-compose.yml
, add the version of hugo desired todocker-compose.yml
fileimage
tag:
name: my-hugo-site
services:
server:
image: hugomods/hugo:go-git-non-root-0.147.1
command: server -D
volumes:
- ./:/src # maps current working directory to /src
- ~/hugo_cache:/tmp/hugo_cache
ports:
- 1313:1313
Note! Useful when using a theme requiring a specific version of hugo.
docker compose up server
- Verify the site is available.