Tech Undocs

Appearance

hugodocker

Building custom Hugo Docker images ​

Discover the process of building tailored Docker images for Hugo projects. From official releases to custom entrypoint scripts, this comprehensive guide helps developers streamline their Hugo deployments using Docker.

Official Hugo releases ​

Hugo provides official releases for various platforms and architectures, ensuring that developers can easily access the latest features and improvements. You can find all available releases on the GitHub. The following are some of the key release formats:

  • Standard Hugo versions:
    • hugo_{version}_linux-amd64.deb
    • hugo_{version}_linux-amd64.tar.gz
    • hugo_{version}_linux-arm64.deb
    • hugo_{version}_linux-arm64.tar.gz
  • Extended Hugo versions (with additional features):
    • hugo_extended_{version}_linux-amd64.deb
    • hugo_extended_{version}_linux-amd64.tar.gz
    • hugo_extended_{version}_linux-arm64.deb
    • hugo_extended_{version}_linux-arm64.tar.gz

These releases can be used to create custom Docker images or installed directly on your system, providing flexibility for various development environments.

Custom Docker images ​

You can create custom Docker images for Hugo to suit your specific needs. Here are two examples:

Extended Hugo with Node.js ​

This Dockerfile creates an image that combines the extended version of Hugo with a Node.js environment:

dockerfile
FROM node:lts

ARG TARGETARCH
ARG HUGO_VERSION

RUN curl -L https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-${TARGETARCH}.deb -o hugo.deb && dpkg -i hugo.deb && rm hugo.deb

VOLUME /project
WORKDIR /project

EXPOSE 1313

ENTRYPOINT ["hugo"]
CMD ["--help"]

This setup is particularly useful for Hugo projects that require Node.js for asset processing or other JavaScript-based tools. Key features include:

  • Base image: Uses the official Node.js LTS (Long Term Support) image, ensuring a stable Node.js environment.
  • Hugo installation: Downloads and installs the extended version of Hugo, which includes additional features like Sass/SCSS processing.
  • Architecture flexibility: Uses the TARGETARCH argument to support different CPU architectures.
  • Project volume: Sets up a volume for the project files, allowing easy mounting of local directories.
  • Port exposure: Exposes port 1313, which is Hugo's default development server port.

This image is ideal for projects that leverage Hugo's extended features and require Node.js for tasks like running build scripts, managing dependencies with npm, or using JavaScript-based asset pipelines.

Standard Hugo on Red Hat UBI ​

This Dockerfile creates an image with the standard version of Hugo on Red Hat Universal Base Image (UBI):

dockerfile
FROM redhat/ubi9

ARG TARGETARCH
ARG HUGO_VERSION

RUN curl -L https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_linux-${TARGETARCH}.tar.gz hugo.tar.gz && tar -xf hugo.tar.gz && mv hugo /usr/local/bin && rm hugo.tar.gz

VOLUME /project
WORKDIR /project

EXPOSE 1313

ENTRYPOINT ["hugo"]
CMD ["--help"]

This configuration is designed for environments that prioritize security and stability. Key aspects include:

  • Base image: Uses Red Hat's Universal Base Image 9, which is a minimal, layered image that adheres to security best practices.
  • Hugo installation: Installs the standard version of Hugo, suitable for projects that don't require the extended features.
  • Manual installation: Downloads the Hugo binary, extracts it, and moves it to the system path, providing more control over the installation process.
  • Minimal footprint: By using the standard Hugo version and a minimal base image, this configuration results in a smaller container size.
  • Enterprise-ready: The use of UBI makes this image suitable for enterprise environments that require Red Hat-compatible containers.

This setup is particularly beneficial for projects that need to comply with strict security policies or those that prefer a Red Hat-based environment. It's also a good choice for simpler Hugo projects that don't require the additional features of the extended version.

Both of these custom images offer different advantages depending on your project requirements, development environment, and deployment constraints. The Extended Hugo with Node.js is more feature-rich and suitable for complex front-end workflows, while the Standard Hugo on Red Hat UBI is optimized for security and minimal size, making it ideal for enterprise deployments or simpler Hugo projects.

Building and running custom images ​

To build a custom Hugo Docker image:

sh
docker build -t custom-hugo:0.136.3 --build-arg HUGO_VERSION=0.136.3 .

To run the custom Hugo Docker image:

sh
docker run -it -v $(pwd):/project -p 1313:1313 custom-hugo:0.136.3 server

Custom entrypoint script ​

For more flexibility, you can use a custom entrypoint script. This script allows for custom initialization steps and ensures npm packages are installed if required. Here's an example of such a script:

sh
#!/bin/sh

# Check for custom entrypoint
if [ -f hugo-docker-entrypoint.sh ]; then
  sh hugo-docker-entrypoint.sh "$@"
  exit $?
fi

# Install npm packages if needed
if [ -f package.json ] && [ ! -d node_modules ]; then
  npm i
fi

exec "hugo" "$@"

To use this custom entrypoint script in your Docker image, you need to make two changes to your Dockerfile:

  1. Copy the entrypoint script into the image.
  2. Set the script as the entrypoint for the container.

Here's how you can modify your Dockerfile to incorporate the custom entrypoint script:

dockerfile
FROM node:lts  # or your preferred base image

ARG TARGETARCH
ARG HUGO_VERSION

# ... (previous RUN commands to install Hugo) ...

# Copy the entrypoint script into the image
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

VOLUME /project
WORKDIR /project

EXPOSE 1313

# Set the custom entrypoint script
ENTRYPOINT ["/entrypoint.sh"]
CMD ["--help"]

The key changes are:

  1. COPY entrypoint.sh /entrypoint.sh: This line copies your custom entrypoint script into the root directory of the image.
  2. RUN chmod +x /entrypoint.sh: This ensures that the script is executable.
  3. ENTRYPOINT ["/entrypoint.sh"]: This sets the custom script as the entrypoint for the container.

By using this custom entrypoint script, you gain several advantages:

  • Flexibility to perform additional setup steps before running Hugo.
  • Ability to check for and execute project-specific initialization scripts.
  • Automatic installation of npm packages if a package.json file is present.
  • Seamless fallback to standard Hugo behavior if no custom steps are needed.

This approach allows you to create a more versatile Hugo Docker image that can adapt to different project requirements without needing to modify the image itself. It's particularly useful for teams working on multiple Hugo projects with varying setup needs.