Skip to content

Commit c12a7a1

Browse files
jmooringjmooring
committed
Document usage of official Docker image
Closes #2727
1 parent 612b852 commit c12a7a1

File tree

4 files changed

+220
-28
lines changed

4 files changed

+220
-28
lines changed

‎content/en/installation/bsd.md‎

Lines changed: 54 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -69,12 +69,59 @@ doas pkg_add hugo
6969

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

72+
## Docker container
73+
74+
### Prerequisites {#docker-prerequisites}
75+
76+
Before running the Docker container locally you must install Docker. See the [installation instructions].
77+
78+
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.
79+
80+
To prevent ownership and permission problems, create the Hugo [cache directory](#cache-directory) and ignore the error if the directory already exists:
81+
82+
```text
83+
mkdir -p $HOME/.cache/hugo_cache
84+
```
85+
86+
[ci/cd]: https://en.wikipedia.org/wiki/CI/CD
87+
[installation instructions]: https://wiki.freebsd.org/Docker
88+
89+
### Commands
90+
91+
To build your site using the latest version:
92+
93+
{{< code copy=true >}}
94+
docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache ghcr.io/gohugoio/hugo:latest build
95+
{{< /code >}}
96+
97+
To build your site and start the embedded web server using the latest version:
98+
99+
{{< code copy=true >}}
100+
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"
101+
{{< /code >}}
102+
103+
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:
104+
105+
{{< code copy=true >}}
106+
docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache ghcr.io/gohugoio/hugo:v0.136.1 build
107+
{{< /code >}}
108+
109+
[tagged image versions]: https://github.com/gohugoio/hugo/pkgs/container/hugo/versions?filters%5Bversion_type%5D=tagged
110+
111+
### Cache directory
112+
113+
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.
114+
115+
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.
116+
72117
## Comparison
73118

74-
||Prebuilt binaries|Repository packages|Build from source
75-
:--|:--:|:--:|:--:
76-
Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
77-
Easy to upgrade?|:heavy_check_mark:|varies|:heavy_check_mark:
78-
Easy to downgrade?|:heavy_check_mark:|varies|:heavy_check_mark:
79-
Automatic updates?|:x:|varies|:x:
80-
Latest version available?|:heavy_check_mark:|varies|:heavy_check_mark:
119+
||Prebuilt binaries|Repository packages|Build&nbsp;from source|Docker container
120+
|:--|:-:|:-:|:-:|:-:
121+
|Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:[^1]
122+
|Easy to upgrade?|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark:
123+
|Easy to downgrade?|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark:
124+
|Automatic updates?|:x:|varies|:x:|:x:
125+
|Latest version available?|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark:
126+
127+
[^1]: Docker containers do not require installation, but you must install Docker before you can run a container. See the [prerequisites](#docker-prerequisites) section above.

‎content/en/installation/linux.md‎

Lines changed: 54 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -203,15 +203,62 @@ sudo xbps-install -S hugo
203203

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

206+
## Docker container
207+
208+
### Prerequisites {#docker-prerequisites}
209+
210+
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].
211+
212+
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.
213+
214+
To prevent ownership and permission problems, create the Hugo [cache directory](#cache-directory) and ignore the error if the directory already exists:
215+
216+
```text
217+
mkdir -p $HOME/.cache/hugo_cache
218+
```
219+
220+
[ci/cd]: https://en.wikipedia.org/wiki/CI/CD
221+
[docker desktop]: https://docs.docker.com/desktop/install/linux/
222+
[docker engine]: https://docs.docker.com/engine/install/
223+
224+
### Commands
225+
226+
To build your site using the latest version:
227+
228+
{{< code copy=true >}}
229+
docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache ghcr.io/gohugoio/hugo:latest build
230+
{{< /code >}}
231+
232+
To build your site and start the embedded web server using the latest version:
233+
234+
{{< code copy=true >}}
235+
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"
236+
{{< /code >}}
237+
238+
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:
239+
240+
{{< code copy=true >}}
241+
docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache ghcr.io/gohugoio/hugo:v0.136.1 build
242+
{{< /code >}}
243+
244+
[tagged image versions]: https://github.com/gohugoio/hugo/pkgs/container/hugo/versions?filters%5Bversion_type%5D=tagged
245+
246+
### Cache directory
247+
248+
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.
249+
250+
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.
251+
206252
## Comparison
207253

208-
||Prebuilt binaries|Package managers|Repository packages|Build from source
209-
:--|:--:|:--:|:--:|:--:
210-
Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
211-
Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark:
212-
Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|varies|:heavy_check_mark:
213-
Automatic updates?|:x:|varies [^2]|:x:|:x:
214-
Latest version available?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark:
254+
||Prebuilt binaries|Package managers|Repository packages|Build&nbsp;from source|Docker container
255+
|:--|:-:|:-:|:-:|:-:|:-:
256+
|Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:[^3]
257+
|Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark:
258+
|Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|varies|:heavy_check_mark:|:heavy_check_mark:
259+
|Automatic updates?|:x:|varies [^2]|:x:|:x:|:x:
260+
|Latest version available?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark:
215261

216262
[^1]: Easy if a previous version is still installed.
217263
[^2]: Snap packages are automatically updated. Homebrew requires advanced configuration.
264+
[^3]: Docker containers do not require installation, but you must install Docker Desktop or Docker Engine before you can run a container. See the [prerequisites](#docker-prerequisites) section above.

‎content/en/installation/macos.md‎

Lines changed: 53 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -37,15 +37,61 @@ sudo port install hugo
3737

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

40+
## Docker container
41+
42+
### Prerequisites {#docker-prerequisites}
43+
44+
Before running the Docker container locally you must install Docker Desktop. See the [installation instructions].
45+
46+
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.
47+
48+
To prevent ownership and permission problems, create the Hugo [cache directory](#cache-directory) and ignore the error if the directory already exists:
49+
50+
```text
51+
mkdir -p $HOME/Library/Caches/hugo_cache
52+
```
53+
54+
[ci/cd]: https://en.wikipedia.org/wiki/CI/CD
55+
[installation instructions]: https://docs.docker.com/desktop/install/mac-install/
56+
57+
### Commands
58+
59+
To build your site using the latest version:
60+
61+
{{< code copy=true >}}
62+
docker run --rm -v .:/project -v $HOME/Library/Caches/hugo_cache:/cache ghcr.io/gohugoio/hugo:latest build
63+
{{< /code >}}
64+
65+
To build your site and start the embedded web server using the latest version:
66+
67+
{{< code copy=true >}}
68+
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"
69+
{{< /code >}}
70+
71+
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:
72+
73+
{{< code copy=true >}}
74+
docker run --rm -v .:/project -v $HOME/Library/Caches/hugo_cache:/cache ghcr.io/gohugoio/hugo:v0.136.1 build
75+
{{< /code >}}
76+
77+
[tagged image versions]: https://github.com/gohugoio/hugo/pkgs/container/hugo/versions?filters%5Bversion_type%5D=tagged
78+
79+
### Cache directory
80+
81+
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.
82+
83+
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.
84+
4085
## Comparison
4186

42-
||Prebuilt binaries|Package managers|Build from source
43-
:--|:--:|:--:|:--:
44-
Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|
45-
Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
46-
Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|:heavy_check_mark:
47-
Automatic updates?|:x:|:x: [^2]|:x:
48-
Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
87+
||Prebuilt binaries|Package managers|Build&nbsp;from source|Docker container
88+
|:--|:-:|:-:|:-:|:-:
89+
|Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:[^3]
90+
|Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
91+
|Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|:heavy_check_mark:|:heavy_check_mark:
92+
|Automatic updates?|:x:|:x: [^2]|:x:|:x:
93+
|Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
4994

5095
[^1]: Easy if a previous version is still installed.
5196
[^2]: Possible but requires advanced configuration.
97+
[^3]: Docker containers do not require installation, but you must install Docker Desktop before you can run a container. See the [prerequisites](#docker-prerequisites) section above.

‎content/en/installation/windows.md‎

Lines changed: 59 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -69,15 +69,67 @@ winget uninstall --name "Hugo (Extended)"
6969
See these [detailed instructions](https://discourse.gohugo.io/t/41370) to install GCC on Windows.
7070
{{% /note %}}
7171

72+
## Docker container
73+
74+
{{% note %}}
75+
Run the commands in this section from [PowerShell] or a Linux terminal such as WSL or Git Bash. Do not use the Command Prompt.
76+
77+
[PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows
78+
{{% /note %}}
79+
80+
### Prerequisites {#docker-prerequisites}
81+
82+
Before running the Docker container locally you must install Docker Desktop. See the [installation instructions].
83+
84+
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.
85+
86+
To prevent ownership and permission problems, create the Hugo [cache directory](#cache-directory) and ignore the error if the directory already exists:
87+
88+
```text
89+
mkdir -f $Env:LocalAppData/hugo_cache
90+
```
91+
92+
[ci/cd]: https://en.wikipedia.org/wiki/CI/CD
93+
[installation instructions]: https://docs.docker.com/desktop/install/windows-install/
94+
95+
### Commands
96+
97+
To build your site using the latest version:
98+
99+
{{< code copy=true >}}
100+
docker run --rm -v .:/project -v $Env:LocalAppData/hugo_cache:/cache ghcr.io/gohugoio/hugo:latest build
101+
{{< /code >}}
102+
103+
To build your site and start the embedded web server using the latest version:
104+
105+
{{< code copy=true >}}
106+
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"
107+
{{< /code >}}
108+
109+
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:
110+
111+
{{< code copy=true >}}
112+
docker run --rm -v .:/project -v $Env:LocalAppData/hugo_cache:/cache ghcr.io/gohugoio/hugo:v0.136.1 build
113+
{{< /code >}}
114+
115+
[tagged image versions]: https://github.com/gohugoio/hugo/pkgs/container/hugo/versions?filters%5Bversion_type%5D=tagged
116+
117+
### Cache directory
118+
119+
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.
120+
121+
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.
122+
72123
## Comparison
73124

74-
||Prebuilt binaries|Package managers|Build from source
75-
:--|:--:|:--:|:--:
76-
Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|
77-
Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
78-
Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^2]|:heavy_check_mark:
79-
Automatic updates?|:x:|:x: [^1]|:x:
80-
Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
125+
||Prebuilt binaries|Package managers|Build&nbsp;from source|Docker container
126+
|:--|:-:|:-:|:-:|:-:
127+
|Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:[^3]
128+
|Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
129+
|Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^2]|:heavy_check_mark:|:heavy_check_mark:
130+
|Automatic updates?|:x:|:x: [^1]|:x:|:x:
131+
|Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
81132

82133
[^1]: Possible but requires advanced configuration.
83134
[^2]: Easy if a previous version is still installed.
135+
[^3]: Docker containers do not require installation, but you must install Docker Desktop before you can run a container. See the [prerequisites](#docker-prerequisites) section above.

0 commit comments

Comments
 (0)