Running the Handbook in Docker
Docker runs the preview tools in a container, so you can see your edits in a browser without installing Node.js, Go, Hugo, or Make on your computer.
Before you start
- Clone the handbook repository if you have not already.
- Follow the handbook’s Docker Desktop and alternatives guidance to choose and install a container app, such as Rancher Desktop. If you already have Docker with Compose working, use your existing setup.
- For Rancher Desktop, select dockerd (moby) in the container engine settings to use the Docker commands below. Kubernetes is not needed for this preview.
- Open your container app and wait for it to finish starting. Keep it running while you preview.
Open a terminal in your cloned repository folder, where compose.yml lives.
In VS Code, use Terminal > New Terminal after opening that folder.
Check that Docker and Compose are available:
docker info
docker compose version
If either command fails, complete your container app’s setup before continuing.
For docker: command not found, check its command-line tool setup and reopen your terminal.
For a connection error, check that the app is running.
Run the handbook
From the same terminal, start the preview:
docker compose up
The first startup takes longer while the image, dependencies, and data download. Wait until Hugo reports that its web server is available, then open http://localhost:1313/. Keep the command running while you edit files in your editor. Saving a file triggers a rebuild so you can check the result in your browser.
Press Ctrl+C in the terminal to stop the preview. To remove the stopped container, run:
docker compose down
Run docker compose up again when you want to resume editing.
If port 1313 is already in use, run HUGO_PORT=1328 docker compose up and open
http://localhost:1328/ instead.
For build errors or refreshing an older environment, see the
troubleshooting guide.
How the preview works
Compose uses the same pinned Hugo image as CI/CD. It installs project dependencies,
including Dart Sass, synchronizes data, and starts the preview through the Makefile.
You do not need to run npm ci or ./scripts/sync-data.sh separately.
Dependencies and caches live in Docker volumes, separate from your host packages.
Each startup runs npm ci, so dependency changes in the lockfile take effect.
Run only one preview or build at a time per checkout, because they share generated files. Stop the preview before switching between native and container builds.
Build the site
If you need the generated site files instead of a live preview, stop the preview
and run a production build into public/:
docker compose run --rm hugo make build HUGO_ARGS=--enableGitInfo
Makefile shortcuts and Git worktrees
If Make is installed, use make compose-view, make compose-build, and
make compose-down for the same Compose commands.
For Git worktrees, use these Makefile shortcuts. They also provide the Git metadata mount needed to resolve the worktree’s original repository:
make compose-view
Direct Docker without Compose
If your Docker-compatible engine does not provide Compose, use the existing
Makefile targets. These use docker run directly:
make docker-view
make docker-build
They use the same image and setup script as Compose, including Git worktree support.
Dependencies and caches use temporary volumes removed when the command exits.
make docker-prep checks dependency installation in a temporary container; preview
and build commands also install dependencies automatically.
Use make docker-view HUGO_PORT=1328 to choose another port. Additional Docker
options can be passed through DOCKER_ARGS, and Hugo options through HUGO_ARGS.
If Make is not installed on your host, run this from the root of a regular clone:
HUGO_VERSION=$(sed -n 's/^hugo-extended //p' .tool-versions)
docker run --rm --init --user root --entrypoint sh \
--publish 127.0.0.1:1313:1313 \
--volume "$PWD:$PWD" --workdir "$PWD" \
--volume "$PWD/node_modules" --volume /cache \
--env HUGO_CACHEDIR=/cache/hugo --env GOPATH=/cache/go \
--env npm_config_cache=/cache/npm \
--env HUGOxPARAMSxGITLAB_API_KEY --env HANDBOOK_SYNC_TOKEN --env WWW_GITLAB_COM_REF \
"ghcr.io/gohugoio/hugo:v$HUGO_VERSION" \
scripts/docker-entrypoint.sh make view \
HUGO_ARGS="--bind 0.0.0.0 --port 1313 --poll 1s"
Open http://localhost:1313/. Press Ctrl+C to stop and remove the container.
This uses the repository’s pinned Hugo version and installs the required tools
inside the container. For a static build, replace make view and its HUGO_ARGS
with make build HUGO_ARGS=--enableGitInfo.
For a Git worktree, use make docker-view so the original repository’s Git
metadata is also mounted. Your engine must support the Docker CLI options used
above; select its Docker context or set DOCKER_HOST as directed by your engine.
0f66367e)
