Skip to content

Document usage of official Docker image #2741

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.

Sign up for GitHub

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

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

Document usage of official Docker image #2741

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 0 additions & 10 deletions content/en/installation/bsd.md
View file
Open in desktop
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Docker is not supported on BSD :-)

Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,6 @@ Unless your specific deployment needs require the extended/deploy edition, we re

Most BSD derivatives maintain a repository for commonly installed applications. Please note that these repositories may not contain the [latest release].

[latest release]: https://github.com/gohugoio/hugo/releases/latest

### DragonFly BSD

[DragonFly BSD] includes Hugo in its package repository. To install the extended edition of Hugo:
Expand All @@ -30,8 +28,6 @@ Most BSD derivatives maintain a repository for commonly installed applications.
sudo pkg install gohugo
```

[DragonFly BSD]: https://www.dragonflybsd.org/

### FreeBSD

[FreeBSD] includes Hugo in its package repository. To install the extended edition of Hugo:
Expand All @@ -40,8 +36,6 @@ sudo pkg install gohugo
sudo pkg install gohugo
```

[FreeBSD]: https://www.freebsd.org/

### NetBSD

[NetBSD] includes Hugo in its package repository. To install the extended edition of Hugo:
Expand All @@ -50,8 +44,6 @@ sudo pkg install gohugo
sudo pkgin install go-hugo
```

[NetBSD]: https://www.netbsd.org/

### OpenBSD

[OpenBSD] includes Hugo in its package repository. This will prompt you to select which edition of Hugo to install:
Expand All @@ -60,8 +52,6 @@ sudo pkgin install go-hugo
doas pkg_add hugo
```

[OpenBSD]: https://www.openbsd.org/

{{% include "/_common/installation/04-build-from-source.md" %}}

## Comparison
Expand Down
43 changes: 43 additions & 0 deletions content/en/installation/linux.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -172,6 +172,46 @@ sudo xbps-install -S hugo

{{% include "/_common/installation/04-build-from-source.md" %}}

## Docker container

### Prerequisites {#docker-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](g) 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
```

### Commands

To build your site using the latest version:

```sh {copy=true}
docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache ghcr.io/gohugoio/hugo:latest build
```

To build your site and start the embedded web server using the latest version:

```sh {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"
```

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:

```sh {copy=true}
docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache ghcr.io/gohugoio/hugo:v0.136.1 build
```

### 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
Expand All @@ -190,6 +230,8 @@ Latest version available?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_ch
[Calculate Linux]: https://www.calculate-linux.org/
[CentOS]: https://www.centos.org/
[Debian]: https://www.debian.org/
[Docker Desktop]: https://docs.docker.com/desktop/setup/install/linux/
[Docker Engine]: https://docs.docker.com/engine/install/
[elementary OS]: https://elementary.io/
[EndeavourOS]: https://endeavouros.com/
[Exherbo]: https://www.exherbolinux.org/
Expand All @@ -212,6 +254,7 @@ Latest version available?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_ch
[Snap]: https://snapcraft.io/
[Solus]: https://getsol.us/
[strictly confined]: https://snapcraft.io/docs/snap-confinement
[tagged image versions]: https://github.com/gohugoio/hugo/pkgs/container/hugo/versions?filters%5Bversion_type%5D=tagged
[Ubuntu]: https://ubuntu.com/
[USE]: https://packages.gentoo.org/packages/www-apps/hugo
[Void Linux]: https://voidlinux.org/
Expand Down
46 changes: 44 additions & 2 deletions content/en/installation/macos.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,10 +28,48 @@ Unless your specific deployment needs require the extended/deploy edition, we re
sudo port install hugo
```

[MacPorts]: https://www.macports.org/

{{% include "/_common/installation/04-build-from-source.md" %}}

## Docker container

### Prerequisites {#docker-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](g) 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
```

### Commands

To build your site using the latest version:

```sh {copy=true}
docker run --rm -v .:/project -v $HOME/Library/Caches/hugo_cache:/cache ghcr.io/gohugoio/hugo:latest build
```

To build your site and start the embedded web server using the latest version:

```sh {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"
```

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:

```sh {copy=true}
docker run --rm -v .:/project -v $HOME/Library/Caches/hugo_cache:/cache ghcr.io/gohugoio/hugo:v0.136.1 build
```

### 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
Expand All @@ -44,3 +82,7 @@ Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mar

[^1]: Easy if a previous version is still installed.
[^2]: Possible but requires advanced configuration.

[installation instructions]: https://docs.docker.com/desktop/install/mac-install/
[MacPorts]: https://www.macports.org/
[tagged image versions]: https://github.com/gohugoio/hugo/pkgs/container/hugo/versions?filters%5Bversion_type%5D=tagged
46 changes: 46 additions & 0 deletions content/en/installation/windows.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,49 @@ winget uninstall --name "Hugo (Extended)"
> [!note]
> See these [detailed instructions](https://discourse.gohugo.io/t/41370) to install GCC on Windows.

## 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.

### Prerequisites {#docker-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](g) 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
```

### Commands

To build your site using the latest version:

```sh {copy=true}
docker run --rm -v .:/project -v $Env:LocalAppData/hugo_cache:/cache ghcr.io/gohugoio/hugo:latest build
```

To build your site and start the embedded web server using the latest version:

```sh {copy=true}
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"
```

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:

```sh {copy=true}
docker run --rm -v .:/project -v $Env:LocalAppData/hugo_cache:/cache ghcr.io/gohugoio/hugo:v0.136.1 build
```

### 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
Expand All @@ -70,5 +113,8 @@ Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mar
[^2]: Easy if a previous version is still installed.

[Chocolatey]: https://chocolatey.org/
[installation instructions]: https://docs.docker.com/desktop/install/windows-install/
[PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows
[Scoop]: https://scoop.sh/
[tagged image versions]: https://github.com/gohugoio/hugo/pkgs/container/hugo/versions?filters%5Bversion_type%5D=tagged
[Winget]: https://learn.microsoft.com/en-us/windows/package-manager/