The Kool Way to Run Hugo Static Sites on Docker

In just 2 simple steps, you can use Kool to start a new Hugo application running in a local Docker development environment.

Kool is a free, open source CLI tool that makes local development with Docker super easy. Kool CLI will level up your development workflow, and help you and your team improve the way you develop and deploy cloud native applications.

Requirements

If you haven't done so already, you first need to install Docker and the Kool CLI.

If you already have kool installed, make sure you're running the latest version with kool self-update.

Step 1 – Create a New Hugo Application

Use the kool create command to create your new Hugo project.

$ kool create hugo my-project

IMPORTANT: if you're on Windows WSL or Linux, you should run sudo kool create hugo my-project as the superuser (via sudo) to avoid permissions issues when creating the project directory and files.

Under the hood, this command will run kool docker klakegg/hugo:ext-alpine new site my-project using the klakegg/hugo Docker image.

Now, move into your new Hugo project:

$ cd my-project

After installing Hugo, kool create automatically runs the kool preset hugo command, which auto-generates the following configuration files and adds them to your project. As your project evolves, you can easily modify and extend these files to suit your needs.

+docker-compose.yml
+kool.yml

Step 2 – Start Your Local Environment

As mentioned above, the kool preset command added a kool.yml file to your project. To help get you started, kool.yml comes prebuilt with an initial set of scripts based on your chosen framework and stack. Since Hugo requires a few extra steps to create a Hello World site, kool.yml includes a special quickstart script to make it super easy.

Think of kool.yml as an easy-to-use task helper. Instead of writing custom shell scripts, add your own scripts to kool.yml (under the scripts key), and run them with kool run SCRIPT (e.g. kool run hugo). You can add your own single line commands (see hugo below), or add a list of commands that will be executed in sequence (see quickstart below).

scripts:
    hugo: kool docker -p 1313:1313 klakegg/hugo:ext-alpine
    dev: kool run hugo server -D

    # remove or modify to suit the needs of your project
    quickstart:
        - kool start
        - git init
        - git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
        - echo theme = \"ananke\" >> config.toml
        - kool run hugo new posts/my-first-post.md
        - kool run dev

    setup:
        - kool start
        - kool run dev

Go ahead and run kool run quickstart to start your Docker environment and initialize your Hugo site.

$ kool run quickstart

As you can see in kool.yml, the quickstart script does the following in sequence: runs the kool start command to spin up your Docker environment; calls git init to create a Git repository; downloads the Ananke theme; uses an echo command to add the theme to your Hugo config file; adds your first post; and then calls kool run dev to build your Hugo site.

That's it!

Once kool run quickstart finishes, you should be able to access your new site at http://localhost and see the "My New Hugo Site" page. Hooray!

Verify your Docker service containers are running using the kool status command.

$ kool status
+---------+---------+------------------------------+--------------+
| SERVICE | RUNNING | PORTS                        | STATE        |
+---------+---------+------------------------------+--------------+
| app     | Running | 0.0.0.0:80->80/tcp, 1313/tcp | Up 2 minutes |
| static  | Running | 80/tcp                       | Up 2 minutes |
+---------+---------+------------------------------+--------------+

Run kool logs app to see the logs from your running app container.

Use kool logs to see the logs from all running containers. Add the -f option after kool logs to follow the logs (i.e. kool logs -f app).

$ kool logs app
Attaching to my-project_app_1
app_1     |   Non-page files   |  0
app_1     |   Static files     |  0
app_1     |   Processed images |  0
app_1     |   Aliases          |  0
app_1     |   Sitemaps         |  1
app_1     |   Cleaned          |  0
app_1     |
app_1     | Built in 1 ms
app_1     | Watching for changes in /app/{archetypes,content,data,layouts,static}
app_1     | Watching for config changes in /app/config.toml
app_1     | Environment: "DEV"
app_1     | Serving pages from memory
app_1     | Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
app_1     | Web Server is available at http://localhost:80/ (bind address 0.0.0.0)
app_1     | Press Ctrl+C to stop
app_1     |
app_1     | Change of config file detected, rebuilding site.
app_1     | 2021-05-01 20:34:06.306 +0000
app_1     | Rebuilt in 136 ms
app_1     | adding created directory to watchlist /app/content/posts
app_1     |
app_1     | Change detected, rebuilding site.
app_1     | 2021-05-01 20:34:07.305 +0000
app_1     | Source changed "/app/content/posts/my-first-post.md": CREATE
app_1     | Total in 26 ms

When it's time to stop working on the project:

$ kool stop

When you're ready to start coding again:

$ kool start

If you like what we're doing, show your support for this new open source project by starring us on GitHub!

Level Up Your Development Workflow

Once you're up and running with your new Hugo project, you can use the kool CLI to level up your development workflow. Learn more in "How It Works".

Support the Kool Open Source Project

Kool is open source and totally free to use. If you're interested in learning more about the project, please check out kool.dev. If you have questions, need support, or want to get involved, please join our Slack channel.