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 withkool 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 (viasudo
) 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 withkool run SCRIPT
(e.g.kool run hugo
). You can add your own single line commands (seehugo
below), or add a list of commands that will be executed in sequence (seequickstart
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 thekool start
command to spin up your Docker environment; callsgit init
to create a Git repository; downloads the Ananke theme; uses anecho
command to add the theme to your Hugo config file; adds your first post; and then callskool 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 afterkool 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.
kool-dev / kool
From local development to the cloud: web apps development with containers made easy.
About kool
Kool is a CLI tool that brings the complexities of modern software development environments down to earth - making these environments lightweight, fast and reproducible. It reduces the complexity and learning curve of Docker containers for local environments, and offers a simplified interface for using Kubernetes to deploy staging and production environments to the cloud.
Kool gets your local development environment up and running easily and quickly, so you have more time to build a great application. When the time is right, you can then use Kool.dev Cloud to deploy and share your work with the world!
Kool is suitable for solo developers and teams of all sizes. It provides a hassle-free way to handle the Docker basics and immediately start using containers for development, while simultaneously guaranteeing no loss of control over more specialized Docker environments.
Installation
Requirements: Kool is powered by…
Top comments (0)