Document usage of official Docker image

[jmooring]

Closes #2727

Previews:

• BSD
• Linux
• macOS
• Windows

[jmooring]

It would be good if we could test the commands and functionality for each operating system.

OS	Tester	Result
BSD	?	?
Linux	jmooring	pass
macOS	?	?
Windows	jmooring	pass

Note that one of the documented prerequisites, at least on Linux, is creation of the Hugo cache directory. When testing locally on Linux, if $HOME/.cache/hugo_cache does not exist, Hugo creates the directory but the owner and group are set to root. This causes Hugo to throw errors such as:

Error: failed to load modules: failed to download modules: failed to execute 'go [mod download -modcacherw]': failed to execute binary "go" with args [mod download -modcacherw]: go: github.com/jmooring/hugo-content@v0.1.0: mkdir /cache/modules: permission denied
*errors.errorString

Command to create the Hugo cache directory:

OS	Command
BSD	mkdir -p $HOME/.cache/hugo_cache
Linux	mkdir -p $HOME/.cache/hugo_cache
macOS	mkdir -p $HOME/Library/Caches/hugo_cache
Windows	mkdir -f $Env:LocalAppData/hugo_cache (must use Powershell)

Testing

The site that we are using tests these these features and capabilities:

1. Including content from a Hugo module
2. Transpiling Sass to CSS using Dart Sass
3. Vendor prefixing of CSS rules using the postcss, postcss-cli, and autoprefixer Node.js packages
4. Processing CSS files using the tailwindcss and @tailwindcss-cli Node.js packages
5. Encoding images to the WebP format to verify that we're using Hugo's extended edition
6. Including a content file named hugö.md to verify that the Git core.quotepath setting is false¹

Commands for testing on each operating system:

BSD

mkdir -p $HOME/.cache/hugo_cache
git clone https://github.com/jmooring/hugo-docker-test
cd hugo-docker-test
docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:latest server --bind="0.0.0.0"

Linux

mkdir -p $HOME/.cache/hugo_cache
git clone https://github.com/jmooring/hugo-docker-test
cd hugo-docker-test
docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:latest server --bind="0.0.0.0"

macOS

mkdir -p $HOME/Library/Caches/hugo_cache
git clone https://github.com/jmooring/hugo-docker-test
cd hugo-docker-test
docker run --rm -v .:/project -v $HOME/Library/Caches/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:latest server --bind="0.0.0.0"

Windows (use Powershell to run these commands)

mkdir -f $Env:LocalAppData/hugo_cache
git clone https://github.com/jmooring/hugo-docker-test
cd hugo-docker-test
docker run --rm -v .:/project -v $Env:LocalAppData/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:latest server --bind="0.0.0.0"

Footnotes

1. See issue #9810. Git's core.quotepath setting is false if /other/hugö has a non-zero "last modified" date. ↩

[jmooring]

@bep If you have the time and inclination, I would appreciate a review and testing of the Docker instructions for macOS:
https://deploy-preview-2741--gohugoio.netlify.app/installation/macos/#docker-container

As noted in my previous comment, the Linux and Windows instructions work great.

I have no interest in firing up a BSD VM, so that information will be published untested.

[bep]

Your test site fails on my ARM64 MacBook (I'm pretty sure I tested a site with Dart Sass on ...). The error message is clear and simple to understand, though.

I have created a new milestone and will try to fix this/these soon: https://github.com/gohugoio/hugo/milestone/313

Edit in:

• The test site runs fine on Docker images built locally on my MacBook (even if I rm the Hugo cache folder before running). This makes it really easy to debug ... Not.

[bep]

OK, the image in 0.136.2 looks good to me on MacOS (ARM64) for the test site above.

Note that both of these now work:

docker run --rm -v .:/project -v $HOME/Library/Caches/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:v0.136.2 server --bind="0.0.0.0"
docker run --rm -v .:/project -p 1313:1313 ghcr.io/gohugoio/hugo:v0.136.2 server --bind="0.0.0.0"

[jmooring]

Note that both of these now work

I haven't looked at the latest Dockerfile, but why would I use the second one (no persistent cache).

[bep]

I haven't looked at the latest Dockerfile, but why would I use the second one (no persistent cache).

I wouldn't, but for small/simple blogs it does not make much difference in build speed ... As to documentation I would just document the cache variant. But at least now, the user does not have to create the cache dir manually.