Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
jmooring opened this issue Sep 27, 2024 · 6 comments · May be fixed by #2741
Open

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

jmooring opened this issue Sep 27, 2024 · 6 comments · May be fixed by #2741

Comments

@jmooring
Copy link
Member

Some notes here:
gohugoio/hugo#12885

@aarongoldenthal
Copy link

aarongoldenthal commented Sep 28, 2024

@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
Copy link
Member Author

jmooring commented Sep 28, 2024

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
Copy link

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
Copy link
Member Author

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

@aarongoldenthal
Copy link

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
Copy link
Member

bep commented Oct 16, 2024

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.

jmooring added a commit to jmooring/hugo-docs that referenced this issue Oct 16, 2024
jmooring added a commit to jmooring/hugo-docs that referenced this issue Oct 16, 2024
@jmooring jmooring linked a pull request Oct 16, 2024 that will close this issue
jmooring added a commit to jmooring/hugo-docs that referenced this issue Oct 17, 2024
jmooring added a commit to jmooring/hugo-docs that referenced this issue Oct 17, 2024
jmooring added a commit to jmooring/hugo-docs that referenced this issue Oct 17, 2024
jmooring added a commit to jmooring/hugo-docs that referenced this issue Oct 17, 2024
jmooring added a commit to jmooring/hugo-docs that referenced this issue Oct 17, 2024
jmooring added a commit to jmooring/hugo-docs that referenced this issue Oct 19, 2024
jmooring added a commit to jmooring/hugo-docs that referenced this issue Oct 23, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants