Dev Container Setup for Hugo

Imagine a development environment where you never have to worry about mismatched library versions, missing dependencies, or spending hours setting up a new project. Dev containers in Visual Studio Code (VS Code) are here to make that a reality. These Docker-powered environments are tailored to your codebase, ensuring everything runs smoothly, consistently, and with minimal setup.

In this guide, I’ll walk you through the process of setting up a dev container from scratch and setting it up for your Hugo project.  Let’s get started!

What are Dev containers in VS Code?

Development containers, or dev containers within Visual Studio Code (VS Code), are Docker containers configured to provide a fully featured development environment you can work within.  

What is the point of Dev containers?

Dev containers can configured to run an application, to have separate tools, libraries runtimes, dependencies, or whatever is needed to run your codebase. 

How many times have you worked on a project and had problems trying to set up your laptop to have the right version of a library or runtime and had trouble and wasted hours?  If you set up a dev container you can be sure the environment is set up for that codebase, and better yet you can share the dev container with colleagues making their life easier to work on that codebase as well. 

Prerequisites

Whether you are a macOS user or a Windows user, you need to have the following installed:

• Visual Studio Code (VS Code)
• Dev Containers extension installed

I have prepared this guide as a Windows user, steps may be different for macOS users. 

Dev Container Setup

In the bottom left-hand corner of VS Code click on the container button. 

The setup wizard will pop up at the top of your screen. 

When it does click on New Dev Container

The setup wizard will check if Docker is already installed, if it’s not it will ask if you want to install Docker within WSL, say Install, as this will install Docker within the Windows Subsystem for Linux. 

Once the installation has been completed, restart your laptop and relaunch VS Code. 

Click on the button in the button in the left-hand corner of VS Code again. 

The setup wizard will pop up at the top of your screen. 

When it does click on New Dev Container

The next step is to select the template you would like to use.  In this case, I am going to select the Ubuntu configuration template.   This template already has Git installed. 

The container will launch and start to set up the necessary parts for it to be usable. 

When it finishes loading click on the container button in the left-hand corner again.  This will pop up the menu again.  Be sure to select Configure Container Features.  We are now going to install Hugo and Go. 

Search for Go. There are several options, but I use the official dev containers version. Click OK. 

You’ll be asked how you want to configure this installation, select Keep Defaults. 

Next search for Hugo.  There should only be one option, select it and click OK. 

This time you want to select Configure options. 

Select the version you want to install, I always go for the latest. Next, you will be asked if you want to install the extended version of Hugo or not, again I always select yes to this as some themes need it. 

When you’ve selected these options, VS Code will alert you that your container configuration has changed and needs to be rebuilt. Be sure to rebuild it. 

Create Hugo website

First of all, we have to create a new site. In the root folder then run:

hugo new site . --force

In the project I have created, I have installed Hugo bigspring-light theme. Let’s see how.

In the root folder run:

git clone https://github.com/gethugothemes/bigspring-light-hugo themes/bigspring-light

And the last step, let’s copy the example content located in mynewsite/themes/bigspring-light/exampleSite/.

cp -r themes/bigspring-light/exampleSite/* .

We are now ready to build and serve our new site. Let’s run:

hugo server

The VS Code dev container will automatically configure any port forwarding for you.  It’s worth noting that this Hugo theme shows the example website at https://ipadress:port/bigspring/site

If we want to automate the building and the serving actions, we can add a postStartCommand property, with Hugo server set, to the devcontainer.json file.

{
	"name": "Ubuntu",
	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
	"image": "mcr.microsoft.com/devcontainers/base:jammy",
	"features": {
		"ghcr.io/devcontainers/features/go:1": {
			"version": "latest"
		},
		"ghcr.io/devcontainers/features/hugo:1": {
			"extended": true,
			"version": "latest"
		}
	},
	"postStartCommand": "hugo server"
}

In this way, the next time you start the container again, the hugo server command will be run automatically.

Wrap Up

Dev containers in VSCode can be a game changer for engineers working on multiple projects as it offers a consistent, reliable and shareable environment for your individual project.  By following this guide, you’ve learned how to set up a dev container from scratch, configure it for a Hugo project, and even automate tasks like building and serving your site.

Whether you’re working on a team or solo, dev containers eliminate the headaches of environment mismatches and setup struggles. Plus, the ability to share your container configuration ensures everyone can hit the ground running.

Happy coding!