The Kool Way to Run Hugo Static Sites on Docker
Tags: hugo, docker, webdev, tutorial
Published: 2021-07-27 16:02:53

In just 2 simple steps, you can use [**Kool**](https://github.com/kool-dev/kool) to start a new **Hugo** application running in a local Docker development environment.
<!--more-->

> **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](https://kool.dev/docs/getting-started/installation).

> 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](https://kool.dev/docs/commands/kool-create) to create your new Hugo project.

```console
$ 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](https://hub.docker.com/r/klakegg/hugo/) Docker image.

Now, move into your new Hugo project:

```bash
$ cd my-project
```

After installing Hugo, `kool create` automatically runs the [`kool preset hugo` command](https://kool.dev/docs/commands/kool-preset), 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.

```diff
+docker-compose.yml
+kool.yml
```

## Step 2 – Start Your Local Environment

As mentioned above, the [`kool preset` command](https://kool.dev/docs/commands/kool-preset) 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).

```yaml
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.

```bash
$ 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](http://localhost/) and see the "My New Hugo Site" page. Hooray!

---

Verify your Docker service containers are running using the [`kool status` command](/docs/commands/kool-status).

```bash
$ 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`).

```bash
$ 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:

```bash
$ kool stop
```

When you're ready to start coding again:

```bash
$ kool start
```

> If you like what we're doing, show your support for this new open source project by [**starring us on GitHub**](https://github.com/kool-dev/kool)!

##  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"](https://kool.dev/docs/getting-started/how-it-works#better-development-workflow).

## 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](https://kool.dev). If you have questions, need support, or want to get involved, please [join our Slack channel](https://kool.dev/slack).

{% github kool-dev/kool %}