From 987ac24fc5836d26d3ddd75ff13c8685197266ca Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Wed, 16 Oct 2024 13:39:56 -0700 Subject: [PATCH] Document usage of official Docker image Closes #2727 --- content/en/installation/bsd.md | 61 +++++++++++++++++++++++---- content/en/installation/linux.md | 61 +++++++++++++++++++++++---- content/en/installation/macos.md | 60 +++++++++++++++++++++++---- content/en/installation/windows.md | 66 ++++++++++++++++++++++++++---- 4 files changed, 220 insertions(+), 28 deletions(-) diff --git a/content/en/installation/bsd.md b/content/en/installation/bsd.md index 6d00b8b982..4ff0f8e3c7 100644 --- a/content/en/installation/bsd.md +++ b/content/en/installation/bsd.md @@ -64,12 +64,59 @@ doas pkg_add hugo {{% include "installation/_common/04-build-from-source.md" %}} +## Docker container + +### Prerequisites + +Before running the Docker container locally you must install Docker. See the [installation instructions]. + +When building your production site in a [CI/CD] workflow, whether you can run the Docker container depends on the service provider. For example, GitHub Pages and GitLab Pages allow you to run the Docker container. + +To prevent ownership and permission problems, create the Hugo [cache directory](#cache-directory) and ignore the error if the directory already exists: + +```text +mkdir -p $HOME/.cache/hugo_cache +``` + +[ci/cd]: https://en.wikipedia.org/wiki/CI/CD +[installation instructions]: https://wiki.freebsd.org/Docker + +### Commands + +To build your site using the latest version: + +{{< code copy=true >}} +docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:latest build +{{< /code >}} + +To build your site and start the embedded web server using the latest version: + +{{< code copy=true >}} +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" +{{< /code >}} + +To use a specific version, in the commands above replace `latest` with any of the [tagged image versions]. For example, to build your site using v0.136.1: + +{{< code copy=true >}} +docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:v0.136.1 build +{{< /code >}} + +[tagged image versions]: https://github.com/gohugoio/hugo/pkgs/container/hugo/versions?filters%5Bversion_type%5D=tagged + +### Cache directory + +Attaching the host's Hugo cache directory to the container can significantly enhance performance, particularly for large and image-heavy sites. This allows Hugo to reuse previously generated content, reducing the need for repeated processing and transpilation. + +If you are using a custom Hugo cache directory, in the commands above replace `$HOME/.cache/hugo_cache` with the absolute path to your cache directory. + ## Comparison -||Prebuilt binaries|Repository packages|Build from source -:--|:--:|:--:|:--: -Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark: -Easy to upgrade?|:heavy_check_mark:|varies|:heavy_check_mark: -Easy to downgrade?|:heavy_check_mark:|varies|:heavy_check_mark: -Automatic updates?|:x:|varies|:x: -Latest version available?|:heavy_check_mark:|varies|:heavy_check_mark: +||Prebuilt binaries|Repository packages|Build from source|Docker container +:--|:-:|:-:|:-:|:-: +Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:x:[^1] +Easy to upgrade?|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark: +Easy to downgrade?|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark: +Automatic updates?|:x:|varies|:x:|:x: +Latest version available?|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark: + +[^1]: Docker containers don't require installation. However, installing Docker itself can be complex. diff --git a/content/en/installation/linux.md b/content/en/installation/linux.md index 769011212f..4391fd62db 100644 --- a/content/en/installation/linux.md +++ b/content/en/installation/linux.md @@ -181,15 +181,62 @@ sudo eopkg install hugo {{% include "installation/_common/04-build-from-source.md" %}} +## Docker container + +### Prerequisites + +Before running the Docker container locally you must install Docker Desktop or Docker Engine. See the installation instructions for either [Docker Desktop] or [Docker Engine]. + +When building your production site in a [CI/CD] workflow, whether you can run the Docker container depends on the service provider. For example, GitHub Pages and GitLab Pages allow you to run the Docker container. + +To prevent ownership and permission problems, create the Hugo [cache directory](#cache-directory) and ignore the error if the directory already exists: + +```text +mkdir -p $HOME/.cache/hugo_cache +``` + +[ci/cd]: https://en.wikipedia.org/wiki/CI/CD +[docker desktop]: https://docs.docker.com/desktop/install/linux/ +[docker engine]: https://docs.docker.com/engine/install/ + +### Commands + +To build your site using the latest version: + +{{< code copy=true >}} +docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:latest build +{{< /code >}} + +To build your site and start the embedded web server using the latest version: + +{{< code copy=true >}} +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" +{{< /code >}} + +To use a specific version, in the commands above replace `latest` with any of the [tagged image versions]. For example, to build your site using v0.136.1: + +{{< code copy=true >}} +docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:v0.136.1 build +{{< /code >}} + +[tagged image versions]: https://github.com/gohugoio/hugo/pkgs/container/hugo/versions?filters%5Bversion_type%5D=tagged + +### Cache directory + +Attaching the host's Hugo cache directory to the container can significantly enhance performance, particularly for large and image-heavy sites. This allows Hugo to reuse previously generated content, reducing the need for repeated processing and transpilation. + +If you are using a custom Hugo cache directory, in the commands above replace `$HOME/.cache/hugo_cache` with the absolute path to your cache directory. + ## Comparison -||Prebuilt binaries|Package managers|Repository packages|Build from source -:--|:--:|:--:|:--:|:--: -Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark: -Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark: -Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|varies|:heavy_check_mark: -Automatic updates?|:x:|varies [^2]|:x:|:x: -Latest version available?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark: +||Prebuilt binaries|Package managers|Repository packages|Build from source|Docker container +:--|:-:|:-:|:-:|:-:|:-: +Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:x:[^3] +Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark: +Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|varies|:heavy_check_mark:|:heavy_check_mark: +Automatic updates?|:x:|varies [^2]|:x:|:x:|:x: +Latest version available?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark: [^1]: Easy if a previous version is still installed. [^2]: Snap packages are automatically updated. Homebrew requires advanced configuration. +[^3]: Docker containers don't require installation. However, installing Docker itself can be complex. diff --git a/content/en/installation/macos.md b/content/en/installation/macos.md index fa6029679d..2b19e08a8f 100644 --- a/content/en/installation/macos.md +++ b/content/en/installation/macos.md @@ -32,15 +32,61 @@ sudo port install hugo {{% include "installation/_common/04-build-from-source.md" %}} +## Docker container + +### Prerequisites + +Before running the Docker container locally you must install Docker Desktop. See the [installation instructions]. + +When building your production site in a [CI/CD] workflow, whether you can run the Docker container depends on the service provider. For example, GitHub Pages and GitLab Pages allow you to run the Docker container. + +To prevent ownership and permission problems, create the Hugo [cache directory](#cache-directory) and ignore the error if the directory already exists: + +```text +mkdir -p $HOME/Library/Caches/hugo_cache +``` + +[ci/cd]: https://en.wikipedia.org/wiki/CI/CD +[installation instructions]: https://docs.docker.com/desktop/install/mac-install/ + +### Commands + +To build your site using the latest version: + +{{< code copy=true >}} +docker run --rm -v .:/project -v $HOME/Library/Caches/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:latest build +{{< /code >}} + +To build your site and start the embedded web server using the latest version: + +{{< code copy=true >}} +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" +{{< /code >}} + +To use a specific version, in the commands above replace `latest` with any of the [tagged image versions]. For example, to build your site using v0.136.1: + +{{< code copy=true >}} +docker run --rm -v .:/project -v $HOME/Library/Caches/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:v0.136.1 build +{{< /code >}} + +[tagged image versions]: https://github.com/gohugoio/hugo/pkgs/container/hugo/versions?filters%5Bversion_type%5D=tagged + +### Cache directory + +Attaching the host's Hugo cache directory to the container can significantly enhance performance, particularly for large and image-heavy sites. This allows Hugo to reuse previously generated content, reducing the need for repeated processing and transpilation. + +If you are using a custom Hugo cache directory, in the commands above replace `$HOME/Library/Caches/hugo_cache` with the absolute path to your cache directory. + ## Comparison -||Prebuilt binaries|Package managers|Build from source -:--|:--:|:--:|:--: -Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:| -Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark: -Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|:heavy_check_mark: -Automatic updates?|:x:|:x: [^2]|:x: -Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark: +||Prebuilt binaries|Package managers|Build from source|Docker container +:--|:-:|:-:|:-:|:-: +Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:x:[^3] +Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark: +Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|:heavy_check_mark:|:heavy_check_mark: +Automatic updates?|:x:|:x: [^2]|:x:|:x: +Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark: [^1]: Easy if a previous version is still installed. [^2]: Possible but requires advanced configuration. +[^3]: Docker containers don't require installation. However, installing Docker itself can be complex. diff --git a/content/en/installation/windows.md b/content/en/installation/windows.md index 7192645501..cd7d549d81 100644 --- a/content/en/installation/windows.md +++ b/content/en/installation/windows.md @@ -59,15 +59,67 @@ winget install Hugo.Hugo.Extended See these [detailed instructions](https://discourse.gohugo.io/t/41370) to install GCC on Windows. {{% /note %}} +## Docker container + +{{% note %}} +Run the commands in this section from [PowerShell] or a Linux terminal such as WSL or Git Bash. Do not use the Command Prompt. + +[PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows +{{% /note %}} + +### Prerequisites + +Before running the Docker container locally you must install Docker Desktop. See the [installation instructions]. + +When building your production site in a [CI/CD] workflow, whether you can run the Docker container depends on the service provider. For example, GitHub Pages and GitLab Pages allow you to run the Docker container. + +To prevent ownership and permission problems, create the Hugo [cache directory](#cache-directory) and ignore the error if the directory already exists: + +```text +mkdir -f $Env:LocalAppData/hugo_cache +``` + +[ci/cd]: https://en.wikipedia.org/wiki/CI/CD +[installation instructions]: https://docs.docker.com/desktop/install/windows-install/ + +### Commands + +To build your site using the latest version: + +{{< code copy=true >}} +docker run --rm -v .:/project -v %LocalAppData%/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:latest build +{{< /code >}} + +To build your site and start the embedded web server using the latest version: + +{{< code copy=true >}} +docker run --rm -v .:/project -v %LocalAppData%/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:latest server --bind="0.0.0.0" +{{< /code >}} + +To use a specific version, in the commands above replace `latest` with any of the [tagged image versions]. For example, to build your site using v0.136.1: + +{{< code copy=true >}} +docker run --rm -v .:/project -v %LocalAppData%/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:v0.136.1 build +{{< /code >}} + +[tagged image versions]: https://github.com/gohugoio/hugo/pkgs/container/hugo/versions?filters%5Bversion_type%5D=tagged + +### Cache directory + +Attaching the host's Hugo cache directory to the container can significantly enhance performance, particularly for large and image-heavy sites. This allows Hugo to reuse previously generated content, reducing the need for repeated processing and transpilation. + +If you are using a custom Hugo cache directory, in the commands above replace `%LocalAppData%/hugo_cache` with the absolute path to your cache directory. + ## Comparison -||Prebuilt binaries|Package managers|Build from source -:--|:--:|:--:|:--: -Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:| -Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark: -Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^2]|:heavy_check_mark: -Automatic updates?|:x:|:x: [^1]|:x: -Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark: +||Prebuilt binaries|Package managers|Build from source|Docker container +:--|:-:|:-:|:-:|:-: +Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:x:[^3] +Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark: +Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^2]|:heavy_check_mark:|:heavy_check_mark: +Automatic updates?|:x:|:x: [^1]|:x:|:x: +Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark: [^1]: Possible but requires advanced configuration. [^2]: Easy if a previous version is still installed. +[^3]: Docker containers don't require installation. However, installing Docker itself can be complex.