Skip to content

Commit 0fd3946

Browse files
jmooringjmooring
committed
Document usage of official Docker image
1 parent c39ac07 commit 0fd3946

3 files changed

Lines changed: 131 additions & 0 deletions

File tree

‎content/en/installation/linux.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,6 +168,46 @@ sudo xbps-install -S hugo
168168

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

171+
## Docker container
172+
173+
### Prerequisites {#docker-prerequisites}
174+
175+
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].
176+
177+
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.
178+
179+
To prevent ownership and permission problems, create the Hugo [cache directory](#cache-directory) and ignore the error if the directory already exists:
180+
181+
```text
182+
mkdir -p $HOME/.cache/hugo_cache
183+
```
184+
185+
### Commands
186+
187+
To build your site using the latest version:
188+
189+
```sh {copy=true}
190+
docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache ghcr.io/gohugoio/hugo:latest build
191+
```
192+
193+
To build your site and start the embedded web server using the latest version:
194+
195+
```sh {copy=true}
196+
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"
197+
```
198+
199+
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:
200+
201+
```sh {copy=true}
202+
docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache ghcr.io/gohugoio/hugo:v0.136.1 build
203+
```
204+
205+
### Cache directory
206+
207+
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.
208+
209+
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.
210+
171211
## Comparison
172212

173213
 |Prebuilt binaries|Package managers|Repository packages|Build from source
@@ -186,6 +226,8 @@ Latest version available?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_ch
186226
[Calculate Linux]: https://www.calculate-linux.org/
187227
[CentOS]: https://www.centos.org/
188228
[Debian]: https://www.debian.org/
229+
[Docker Desktop]: https://docs.docker.com/desktop/setup/install/linux/
230+
[Docker Engine]: https://docs.docker.com/engine/install/
189231
[EndeavourOS]: https://endeavouros.com/
190232
[Exherbo]: https://www.exherbolinux.org/
191233
[Fedora]: https://getfedora.org/
@@ -213,3 +255,4 @@ Latest version available?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_ch
213255
[most distributions]: https://snapcraft.io/docs/installing-snapd
214256
[openSUSE]: https://www.opensuse.org/
215257
[strictly confined]: https://snapcraft.io/docs/snap-confinement
258+
[tagged image versions]: https://github.com/gohugoio/hugo/pkgs/container/hugo/versions?filters%5Bversion_type%5D=tagged

‎content/en/installation/macos.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,46 @@ sudo port install hugo
2626

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

29+
## Docker container
30+
31+
### Prerequisites {#docker-prerequisites}
32+
33+
Before running the Docker container locally you must install Docker Desktop. See the [installation instructions].
34+
35+
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.
36+
37+
To prevent ownership and permission problems, create the Hugo [cache directory](#cache-directory) and ignore the error if the directory already exists:
38+
39+
```text
40+
mkdir -p $HOME/Library/Caches/hugo_cache
41+
```
42+
43+
### Commands
44+
45+
To build your site using the latest version:
46+
47+
```sh {copy=true}
48+
docker run --rm -v .:/project -v $HOME/Library/Caches/hugo_cache:/cache ghcr.io/gohugoio/hugo:latest build
49+
```
50+
51+
To build your site and start the embedded web server using the latest version:
52+
53+
```sh {copy=true}
54+
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"
55+
```
56+
57+
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:
58+
59+
```sh {copy=true}
60+
docker run --rm -v .:/project -v $HOME/Library/Caches/hugo_cache:/cache ghcr.io/gohugoio/hugo:v0.136.1 build
61+
```
62+
63+
### Cache directory
64+
65+
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.
66+
67+
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.
68+
2969
## Comparison
3070

3171
 |Prebuilt binaries|Package managers|Build from source
@@ -40,3 +80,5 @@ Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mar
4080
[^2]: Possible but requires advanced configuration.
4181

4282
[MacPorts]: https://www.macports.org/
83+
[installation instructions]: https://docs.docker.com/desktop/install/mac-install/
84+
[tagged image versions]: https://github.com/gohugoio/hugo/pkgs/container/hugo/versions?filters%5Bversion_type%5D=tagged

‎content/en/installation/windows.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,49 @@ go install -tags extended,withdeploy github.com/gohugoio/hugo@latest
130130
> [!NOTE]
131131
> See these [detailed instructions][] to install GCC on Windows.
132132
133+
## Docker container
134+
135+
> [!note]
136+
> Run the commands in this section from [PowerShell] or a Linux terminal such as WSL or Git Bash. Do not use the Command Prompt.
137+
138+
### Prerequisites {#docker-prerequisites}
139+
140+
Before running the Docker container locally you must install Docker Desktop. See the [installation instructions].
141+
142+
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.
143+
144+
To prevent ownership and permission problems, create the Hugo [cache directory](#cache-directory) and ignore the error if the directory already exists:
145+
146+
```text
147+
mkdir -f $Env:LocalAppData/hugo_cache
148+
```
149+
150+
### Commands
151+
152+
To build your site using the latest version:
153+
154+
```sh {copy=true}
155+
docker run --rm -v .:/project -v $Env:LocalAppData/hugo_cache:/cache ghcr.io/gohugoio/hugo:latest build
156+
```
157+
158+
To build your site and start the embedded web server using the latest version:
159+
160+
```sh {copy=true}
161+
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"
162+
```
163+
164+
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:
165+
166+
```sh {copy=true}
167+
docker run --rm -v .:/project -v $Env:LocalAppData/hugo_cache:/cache ghcr.io/gohugoio/hugo:v0.136.1 build
168+
```
169+
170+
### Cache directory
171+
172+
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.
173+
174+
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.
175+
133176
## Comparison
134177

135178
 |Prebuilt binaries|Package managers|Build from source
@@ -148,6 +191,9 @@ Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mar
148191
[GCC]: https://gcc.gnu.org/
149192
[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
150193
[Go]: https://go.dev/doc/install
194+
[PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows
151195
[Scoop]: https://scoop.sh/
152196
[Winget]: https://learn.microsoft.com/en-us/windows/package-manager/
153197
[detailed instructions]: https://discourse.gohugo.io/t/41370
198+
[installation instructions]: https://docs.docker.com/desktop/install/windows-install/
199+
[tagged image versions]: https://github.com/gohugoio/hugo/pkgs/container/hugo/versions?filters%5Bversion_type%5D=tagged

0 commit comments

Comments
 (0)