Fix running docs site with docker (#5512)

* Update docs site local build Clean up makefile Ignore container-image.sentinel Fix hugo server errors Ignore files Add makefile credit * Indentation per feedback * Address PR feedback. Remove sentinel file * Remove change to .gitignore
2026-05-17 18:25:26 +00:00 · 2024-01-31 14:54:03 -08:00
parent b1b61ad4cf
commit add367bf2e
6 changed files with 262 additions and 62 deletions
--- a/site/Dockerfile
+++ b/site/Dockerfile
@@ -1,3 +1,46 @@
-FROM klakegg/hugo:ext-alpine
+# Credit to Julien Guyomard (https://github.com/jguyomard)
+# Credit to the Kubernetes Website team.
+# This Dockerfile is based on:
+# (https://github.com/kubernetes/website/blob/main/Dockerfile)

-RUN apk add git
+FROM docker.io/library/golang:1.20-alpine
+
+RUN apk add --no-cache \
+    curl \
+    gcc \
+    g++ \
+    musl-dev \
+    build-base \
+    libc6-compat
+
+ARG HUGO_VERSION
+
+RUN mkdir $HOME/src && \
+    cd $HOME/src && \
+    curl -L https://github.com/gohugoio/hugo/archive/refs/tags/v${HUGO_VERSION}.tar.gz | tar -xz && \
+    cd "hugo-${HUGO_VERSION}" && \
+    go install --tags extended
+
+FROM docker.io/library/golang:1.20-alpine
+
+RUN apk add --no-cache \
+    runuser \
+    git \
+    openssh-client \
+    rsync \
+    npm && \
+    npm install -D autoprefixer postcss-cli
+
+RUN mkdir -p /var/hugo && \
+    addgroup -Sg 1000 hugo && \
+    adduser -Sg hugo -u 1000 -h /var/hugo hugo && \
+    chown -R hugo: /var/hugo && \
+    runuser -u hugo -- git config --global --add safe.directory /src
+
+COPY --from=0 /go/bin/hugo /usr/local/bin/hugo
+
+WORKDIR /src
+
+USER hugo:hugo
+
+EXPOSE 1313
--- a/site/Makefile
+++ b/site/Makefile
@@ -0,0 +1,71 @@
+# Credit to the Kubernetes Website team. (https://github.com/kubernetes/website/blob/main/Makefile)
+HUGO_VERSION      = $(shell grep ^HUGO_VERSION netlify.toml | tail -n 1 | cut -d '=' -f 2 | tr -d " \"\n")
+
+# The CONTAINER_ENGINE variable is used for specifying the container engine. By default 'docker' is used
+# but this can be overridden when calling make, e.g.
+# CONTAINER_ENGINE=podman make container-image
+CONTAINER_ENGINE ?= docker
+IMAGE_REGISTRY ?= registry.local:5000
+IMAGE_VERSION=$(shell scripts/hash-files.sh Dockerfile Makefile | cut -c 1-12)
+CONTAINER_IMAGE   = $(IMAGE_REGISTRY)/kustomize-website-hugo:v$(HUGO_VERSION)-$(IMAGE_VERSION)
+# Mount read-only to allow use with tools like Podman in SELinux mode
+# Container targets don't need to write into /src
+CONTAINER_RUN     = "$(CONTAINER_ENGINE)" run --rm --interactive --tty --volume "$(abspath $(CURDIR)/..):/src:ro,Z"
+
+CCRED=\033[0;31m
+CCEND=\033[0m
+
+.PHONY: help
+help: ## Show this help.
+	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {sub("\\\\n",sprintf("\n%22c"," "), $$2);printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+.PHONY: module-check
+module-check: ## Check if all of the required submodules are correctly initialized.
+	@git submodule status --recursive | awk '/^[+-]/ {err = 1; printf "\033[31mWARNING\033[0m Submodule not initialized: \033[34m%s\033[0m\n",$$2} END { if (err != 0) print "You need to run \033[32mmake module-init\033[0m to initialize missing modules first"; exit err }' 1>&2
+
+.PHONY: module-init
+module-init: ## Initialize required submodules.
+	@echo "Initializing submodules..." 1>&2
+	@git submodule update --init --recursive --depth 1
+
+.PHONY: all
+all: build ## Build site with production settings and put deliverables in ./public
+
+.PHONY: build
+build: module-check ## Build site with non-production settings and put deliverables in ./public
+	hugo --cleanDestinationDir --minify --environment development
+
+.PHONY: build-preview
+build-preview: module-check ## Build site with drafts and future posts enabled
+	hugo --cleanDestinationDir --buildDrafts --buildFuture --environment preview
+
+.PHONY: serve
+serve: module-check ## Boot the development server.
+	hugo server --buildFuture --environment development
+
+## Build a container image for the preview of the website
+.PHONY: container-image
+container-image: netlify.toml Dockerfile hugo.toml
+	$(CONTAINER_ENGINE) build . \
+		--network=host \
+		--tag $(CONTAINER_IMAGE) \
+		--build-arg HUGO_VERSION=$(HUGO_VERSION)
+
+# no build lock to allow for read-only mounts
+## Boot the development server using container.
+.PHONY: container-serve
+container-serve: module-check
+	$(CONTAINER_RUN) \
+		--cap-drop=ALL \
+		--cap-add=AUDIT_WRITE \
+		--read-only \
+		--mount type=tmpfs,destination=/tmp,tmpfs-mode=01777 \
+		-p 1313:1313 $(CONTAINER_IMAGE) \
+		hugo server \
+		  --source site \
+		  --buildFuture \
+		  --environment development \
+		  --bind 0.0.0.0 \
+		  --destination /tmp/hugo \
+		  --cleanDestinationDir \
+		  --noBuildLock
--- a/site/README.md
+++ b/site/README.md
@@ -9,42 +9,114 @@ I put the most effort into the `Documentation` section. The left-menu bar has th

 The top bar is customized with the sections I think make sense to split. However, I have customized nothing else inside the `Community`, `Contribute` and `Blog` sections.

-## Building
+## Running the website locally
+You can run the website locally using [Hugo (Extended version)](https://gohugo.io/), or you can run it in a container runtime. We strongly recommend using the container runtime, as it gives deployment consistency with the live website.

-Build and run using Docker or Hugo, then access the site at `http://localhost:1313`.
+## Prerequisites
+
+To use this repository, you need the following installed locally:
+
+- [npm](https://www.npmjs.com/)
+- [Go](https://go.dev/)
+- [Hugo (Extended version)](https://gohugo.io/)
+- A container runtime, like [Docker](https://www.docker.com/).
+
+Before you start, install the dependencies. Clone the repository and navigate to the site directory:

-### Docker
-Dependencies:
-* [docker](https://docs.docker.com/engine/install/)
-* [docker-compose](https://docs.docker.com/compose/install/)
 ```bash
-docker-compose build
-docker-compomse up -d
+# Clone your repository fork from the previous step
+git clone --recurse-submodules git@github.com:<your github username>/kustomize.git
+cd kustomize/site
 ```

-### hugo
-1. Building using the `hugo` command requires the following dependencies:
-  * [hugo CLI](https://gohugo.io/getting-started/installing/)
-  * [Go](https://go.dev/learn/)
-  * [Node.js](https://nodejs.org/en/)
-  * npm dependencies
-     ```bash
-     npm install -D autoprefixer
-     npm install -D postcss-cli
-     npm install -D postcss
-     ```
-1. Initialize [Docsy](https://www.docsy.dev/docs/) and nested [submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
-   ```bash
-   # In Kustomize repository root directory, fetch docsy submodule at site/themes/docsy.
-   # See alternative submodule cloning options in the submodule documentation linked above.
-   git submodule init
-   git submodule update
-   # Fetch submodules nested in docsy.
-   cd site/themes/docsy
-   git submodule init
-   git submodule update
-   ```
-1. Start in development mode:
-   ```bash
-   hugo serve -D
-   ```
+The Kustomize website uses the [Docsy Hugo theme](https://github.com/google/docsy#readme). Even if you plan to run the website in a container, we strongly recommend pulling in the submodule and other development dependencies by running the following:
+
+### Windows
+```powershell
+# fetch submodule dependencies
+git submodule update --init --recursive --depth 1
+```
+
+### Linux / other Unix
+```bash
+# fetch submodule dependencies
+make module-init
+```
+
+## Running the website using a container
+
+To build the site in a container, run the following:
+
+```bash
+# You can set $CONTAINER_ENGINE to the name of any Docker-like container tool
+# Build the image
+make container-image
+
+# Run the container
+make container-serve
+```
+
+If you see errors, it probably means that the hugo container did not have enough computing resources available. To solve it, increase the amount of allowed CPU and memory usage for Docker on your machine ([MacOS](https://docs.docker.com/desktop/settings/mac/) and [Windows](https://docs.docker.com/desktop/settings/windows/)).
+
+Open up your browser to <http://localhost:1313> to view the website. As you make changes to the source files, Hugo updates the website and forces a browser refresh.
+
+## Running the website locally using Hugo
+
+Make sure to install the Hugo extended version specified by the `HUGO_VERSION` environment variable in the [`netlify.toml`](netlify.toml#L7) file.
+
+To install dependencies, deploy and test the site locally, run:
+
+- For macOS and Linux
+  ```bash
+  npm ci
+  make serve
+  ```
+- For Windows (PowerShell)
+  ```powershell
+  npm ci
+  hugo.exe server --buildFuture --environment development
+  ```
+
+This will start the local Hugo server on port 1313. Open up your browser to <http://localhost:1313> to view the website. As you make changes to the source files, Hugo updates the website and forces a browser refresh.
+
+## Troubleshooting
+
+### error: failed to transform resource: TOCSS: failed to transform "scss/main.scss" (text/x-scss): this feature is not available in your current Hugo version
+
+Hugo is shipped in two set of binaries for technical reasons. The current website runs based on the **Hugo Extended** version only. In the [release page](https://github.com/gohugoio/hugo/releases) look for archives with `extended` in the name. To confirm, run `hugo version` and look for the word `extended`.
+
+### Troubleshooting macOS for too many open files
+
+If you run `make serve` on macOS and receive the following error:
+
+```bash
+ERROR 2020/08/01 19:09:18 Error: listen tcp 127.0.0.1:1313: socket: too many open files
+make: *** [serve] Error 1
+```
+
+Try checking the current limit for open files:
+
+`launchctl limit maxfiles`
+
+Then run the following commands (adapted from <https://gist.github.com/tombigel/d503800a282fcadbee14b537735d202c>):
+
+```shell
+#!/bin/sh
+
+# These are the original gist links, linking to my gists now.
+# curl -O https://gist.githubusercontent.com/a2ikm/761c2ab02b7b3935679e55af5d81786a/raw/ab644cb92f216c019a2f032bbf25e258b01d87f9/limit.maxfiles.plist
+# curl -O https://gist.githubusercontent.com/a2ikm/761c2ab02b7b3935679e55af5d81786a/raw/ab644cb92f216c019a2f032bbf25e258b01d87f9/limit.maxproc.plist
+
+curl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxfiles.plist
+curl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxproc.plist
+
+sudo mv limit.maxfiles.plist /Library/LaunchDaemons
+sudo mv limit.maxproc.plist /Library/LaunchDaemons
+
+sudo chown root:wheel /Library/LaunchDaemons/limit.maxfiles.plist
+sudo chown root:wheel /Library/LaunchDaemons/limit.maxproc.plist
+
+sudo launchctl load -w /Library/LaunchDaemons/limit.maxfiles.plist
+```
+
+This works for Catalina as well as Mojave macOS.
--- a/site/config.toml
+++ b/site/config.toml
@@ -20,7 +20,9 @@ theme = ["docsy"]
 enableGitInfo = true

 # Comment out to enable taxonomies in Docsy
-# disableKinds = ["taxonomy", "taxonomyTerm"]
+disableKinds = ["taxonomy"]
+
+ignoreFiles = [ "README[-]+[a-z]*\\.md", "^node_modules$" ]

 # Highlighting config
 pygmentsCodeFences = true
@@ -58,26 +60,29 @@ id = "UA-00000000-0"
 [languages]
 [languages.en]
 title = "Kustomize"
-description = "Documentation for Kustomize"
 languageName ="English"
 # Weight used for sorting.
 weight = 1
+languagedirection = "ltr"
+i18nDir = "./data/i18n"

-# [languages.no]
-# title = "Kustomize"
-# description = "Docsy er operativsystem for skyen"
-# languageName ="Norsk"
-# contentDir = "content/no"
-# time_format_default = "02.01.2006"
-# time_format_blog = "02.01.2006"

-# [languages.fa]
-# title = "اسناد گلدی"
-# description = "یک نمونه برای پوسته داکسی"
-# languageName ="فارسی"
-# contentDir = "content/fa"
-# time_format_default = "2006.01.02"
-# time_format_blog = "2006.01.02"
+[caches]
+ [caches.assets]
+  dir = ":cacheDir/_gen"
+  maxAge = -1
+ [caches.getcsv]
+  dir = ":cacheDir/:project"
+  maxAge = "60s"
+ [caches.getjson]
+  dir = ":cacheDir/:project"
+  maxAge = "60s"
+ [caches.images]
+  dir = ":cacheDir/_images"
+  maxAge = -1
+ [caches.modules]
+  dir = ":cacheDir/modules"
+  maxAge = -1

 [markup]
  [markup.goldmark]
--- a/site/netlify.toml
+++ b/site/netlify.toml
@@ -1,19 +1,18 @@
 [build]
-  base = "site/"
-  command = "git submodule update --init --recursive --depth 1 && hugo"
-  publish = "publishedSite/"
+base = "site/"
+command = "git submodule update --init --recursive --depth 1 && hugo"
+publish = "publishedSite/"

 [build.environment]
-  HUGO_VERSION = "0.92.2"
-  NODE_ENV = "development"
-  NETLIFY_BUILD_DEBUG = "true"
+HUGO_VERSION = "0.120.3"
+NODE_ENV = "development"
+NETLIFY_BUILD_DEBUG = "true"

 [context.deploy-preview]
-  command = "git submodule update --init --recursive --depth 1 && hugo --enableGitInfo --buildFuture -b $DEPLOY_PRIME_URL"
+command = "git submodule update --init --recursive --depth 1 && hugo --enableGitInfo --buildFuture -b $DEPLOY_PRIME_URL"

 [context.branch-deploy]
-  ignore = "exit 0" # build PRs (deploy preview env) only, not all branches
+ignore = "exit 0" # build PRs (deploy preview env) only, not all branches

 [context.production]
-  ignore = "exit 0" # never deploy production until we're ready to launch
-
+ignore = "exit 0" # never deploy production until we're ready to launch
--- a/site/scripts/hash-files.sh
+++ b/site/scripts/hash-files.sh
@@ -0,0 +1,10 @@
+#!/bin/sh
+# this script emits as hash for the files listed in $@
+if command -v shasum >/dev/null 2>&1; then
+  cat "$@" | shasum -a 256 | cut -d' ' -f1
+elif command -v sha256sum >/dev/null 2>&1; then
+  cat "$@" | sha256sum | cut -d' ' -f1
+else
+  echo "missing shasum tool" 1>&2
+  exit 1
+fi