Skip to content

Commit fdfb55e

Browse files
jmooringjmooring
committed
Document usage of official Docker image
Closes #2727
1 parent d325308 commit fdfb55e

File tree

4 files changed

+220
-28
lines changed

4 files changed

+220
-28
lines changed

‎content/en/installation/bsd.md

+54-7
Original file line numberDiff line numberDiff line change
@@ -64,12 +64,59 @@ doas pkg_add hugo
6464

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

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

69-
||Prebuilt binaries|Repository packages|Build from source
70-
:--|:--:|:--:|:--:
71-
Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
72-
Easy to upgrade?|:heavy_check_mark:|varies|:heavy_check_mark:
73-
Easy to downgrade?|:heavy_check_mark:|varies|:heavy_check_mark:
74-
Automatic updates?|:x:|varies|:x:
75-
Latest version available?|:heavy_check_mark:|varies|:heavy_check_mark:
114+
||Prebuilt binaries|Repository packages|Build&nbsp;from source|Docker container
115+
|:--|:-:|:-:|:-:|:-:
116+
|Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:[^1]
117+
|Easy to upgrade?|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark:
118+
|Easy to downgrade?|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark:
119+
|Automatic updates?|:x:|varies|:x:|:x:
120+
|Latest version available?|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark:
121+
122+
[^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

+54-7
Original file line numberDiff line numberDiff line change
@@ -181,15 +181,62 @@ sudo eopkg install hugo
181181

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

184+
## Docker container
185+
186+
### Prerequisites {#docker-prerequisites}
187+
188+
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].
189+
190+
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.
191+
192+
To prevent ownership and permission problems, create the Hugo [cache directory](#cache-directory) and ignore the error if the directory already exists:
193+
194+
```text
195+
mkdir -p $HOME/.cache/hugo_cache
196+
```
197+
198+
[ci/cd]: https://en.wikipedia.org/wiki/CI/CD
199+
[docker desktop]: https://docs.docker.com/desktop/install/linux/
200+
[docker engine]: https://docs.docker.com/engine/install/
201+
202+
### Commands
203+
204+
To build your site using the latest version:
205+
206+
{{< code copy=true >}}
207+
docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache ghcr.io/gohugoio/hugo:latest build
208+
{{< /code >}}
209+
210+
To build your site and start the embedded web server using the latest version:
211+
212+
{{< code copy=true >}}
213+
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"
214+
{{< /code >}}
215+
216+
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:
217+
218+
{{< code copy=true >}}
219+
docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache ghcr.io/gohugoio/hugo:v0.136.1 build
220+
{{< /code >}}
221+
222+
[tagged image versions]: https://github.com/gohugoio/hugo/pkgs/container/hugo/versions?filters%5Bversion_type%5D=tagged
223+
224+
### Cache directory
225+
226+
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.
227+
228+
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.
229+
184230
## Comparison
185231

186-
||Prebuilt binaries|Package managers|Repository packages|Build from source
187-
:--|:--:|:--:|:--:|:--:
188-
Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
189-
Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark:
190-
Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|varies|:heavy_check_mark:
191-
Automatic updates?|:x:|varies [^2]|:x:|:x:
192-
Latest version available?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark:
232+
||Prebuilt binaries|Package managers|Repository packages|Build&nbsp;from source|Docker container
233+
|:--|:-:|:-:|:-:|:-:|:-:
234+
|Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:[^3]
235+
|Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark:
236+
|Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|varies|:heavy_check_mark:|:heavy_check_mark:
237+
|Automatic updates?|:x:|varies [^2]|:x:|:x:|:x:
238+
|Latest version available?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark:
193239

194240
[^1]: Easy if a previous version is still installed.
195241
[^2]: Snap packages are automatically updated. Homebrew requires advanced configuration.
242+
[^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

+53-7
Original file line numberDiff line numberDiff line change
@@ -32,15 +32,61 @@ sudo port install hugo
3232

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

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

37-
||Prebuilt binaries|Package managers|Build from source
38-
:--|:--:|:--:|:--:
39-
Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|
40-
Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
41-
Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|:heavy_check_mark:
42-
Automatic updates?|:x:|:x: [^2]|:x:
43-
Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
82+
||Prebuilt binaries|Package managers|Build&nbsp;from source|Docker container
83+
|:--|:-:|:-:|:-:|:-:
84+
|Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:[^3]
85+
|Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
86+
|Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|:heavy_check_mark:|:heavy_check_mark:
87+
|Automatic updates?|:x:|:x: [^2]|:x:|:x:
88+
|Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
4489

4590
[^1]: Easy if a previous version is still installed.
4691
[^2]: Possible but requires advanced configuration.
92+
[^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

+59-7
Original file line numberDiff line numberDiff line change
@@ -59,15 +59,67 @@ winget install Hugo.Hugo.Extended
5959
See these [detailed instructions](https://discourse.gohugo.io/t/41370) to install GCC on Windows.
6060
{{% /note %}}
6161

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

64-
||Prebuilt binaries|Package managers|Build from source
65-
:--|:--:|:--:|:--:
66-
Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|
67-
Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
68-
Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^2]|:heavy_check_mark:
69-
Automatic updates?|:x:|:x: [^1]|:x:
70-
Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
115+
||Prebuilt binaries|Package managers|Build&nbsp;from source|Docker container
116+
|:--|:-:|:-:|:-:|:-:
117+
|Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:[^3]
118+
|Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
119+
|Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^2]|:heavy_check_mark:|:heavy_check_mark:
120+
|Automatic updates?|:x:|:x: [^1]|:x:|:x:
121+
|Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
71122

72123
[^1]: Possible but requires advanced configuration.
73124
[^2]: Easy if a previous version is still installed.
125+
[^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)