Document usage of the ghcr.io/gohugoio/hugo Docker image

[jmooring]

Some notes here:
gohugoio/hugo#12885

[aarongoldenthal]

@jmooring I did a quick test with the new container and it worked for me (run from the parent directory containing the source and dest directories):

docker run --rm -v $(pwd):/site ghcr.io/gohugoio/hugo:v0.135.0 --source /site/pages --destination /site/public

Without seeing errors or logs I'm not sure, but it could be the directory you ran from or the user (-u) specification, which you shouldn't need.

Update: seeing your note on permissions, I'm surprised you would need it, but you may on some platforms. All the platforms I use are Windows (Docker Desktop, Rancher Desktop), which run in the current user context, or a Linux container in CI where it's running as the default root user and the build artifacts are saved.

If some other examples would help, this is the Hugo container I've maintained and run for years, and the README has some usage examples (build, run as server, run interactive). It probably needs to be cleaned up, but some of the ${pwd} are Windows PowerShell syntax, and may need to be $(pwd) on other platforms.

[jmooring]

I have been testing by building a site from within its project directory, where the public and resource directories do not yet exist.

the user (-u) specification, which you shouldn't need

Without it, everything's owned by root:

$ ls -al public/

total 48
drwxr-xr-x  5 root     root      4096 Sep 27 18:35 .
drwx--x--x 10 jmooring jmooring  4096 Sep 27 18:35 ..
drwxr-xr-x  2 root     root      4096 Sep 27 18:35 categories
-rw-------  1 root     root     15086 Sep 23 10:39 favicon.ico
-rw-r--r--  1 root     root       418 Sep 27 18:35 index.html
-rw-r--r--  1 root     root       643 Sep 27 18:35 index.xml
drwxr-xr-x  3 root     root      4096 Sep 27 18:35 posts
-rw-r--r--  1 root     root       544 Sep 27 18:35 sitemap.xml
drwxr-xr-x  2 root     root      4096 Sep 27 18:35 tags

From the project directory I should be able to build the site like this:

docker run --rm -v .:/site -u $(id -u):$(id -g) ghcr.io/gohugoio/hugo:v0.135.0

But the container has a default flag of --help, so the command above simply prints help. I need to override the default flag with something to get it to build. For example:

docker run --rm -v .:/site -u $(id -u):$(id -g) ghcr.io/gohugoio/hugo:v0.135.0 --minify

Or, as @aarongoldenthal suggests below:

docker run --rm -v .:/site -u $(id -u):$(id -g) --entrypoint "" ghcr.io/gohugoio/hugo:v0.135.0 hugo

The server command is:

docker run --rm -v .:/site -u $(id -u):$(id -g) -p 1313:1313 ghcr.io/gohugoio/hugo:v0.135.0 server --bind 0.0.0.0

We also need to describe what you can't do (write WebP, transpile Sass, use Hugo modules, etc.).
gohugoio/hugo#12885 (comment)

[aarongoldenthal]

Without it, everything's owned by root:

I see. This is on a Mac? I guess I finally get my +1 for Windows 😉 , there everything inherits the logged on user permissions.

[jmooring]

hugo v0.135.0 linux/amd64 BuildDate=unknown VendorInfo=mage

[aarongoldenthal]

I'll need to think about that... seems like the instructions may need to have a platform-specific component. On Windows the volume is through WSL to the container, and specifying the user either fails with the user not existing (with the actual user), or a permission issue running in the container (picking a random user).

The CMD is a challenge with no flags or or other argument since it's declared in the image. It's not the cleanest, but could override the entrypoint so the hugo command has to be specified:

 docker run --rm -v $(pwd):/site --entrypoint="" ghcr.io/gohugoio/hugo:v0.135.0 hugo

[bep]

Some notes from me (running on MacOS) testing the latest (0.136.0 for now):

Build

docker run --rm -v .:/project -v $HOME/Library/Caches/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:latest build

Start server

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"

---

The one potentially problematic thing to explain to the end user is the /cache volume. We could possibly simplify/improve/somehow make that optional (my Dockefiles skills is not good enough to do that ...), but it's a very important concept to understand for bigger Hugo sites.