Blog » tutorials

Running Hugo on Docker is Really Easy with Kool

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.

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.

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

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 themes/ananke - echo theme = \"ananke\" >> config.toml - kool run hugo new posts/ - 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 |>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 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/": 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!

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".

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

Published Jul 24, 2021


hugo preset

By choosing "Accept all cookies" you agree to the use of cookies to help us provide you with a better user experience and to analyse website usage. Only the essential cookies are necessary for the proper functioning of our website and cannot be refused.
Check out our Cookie Policy and Privacy Policy for more information.