A Docker container that provides a Hugo unit for NGINX Host. This unit only supports Hugo sites that are available via a remote source control repository.
This fork has been made to make it possible to use webhooks from a Gitlab repository.
-
Hugo v0.19
-
Can automatically regenerate your Hugo site upon a push to your GitHub or GitLab repository
-
Can automatically regenerate your Hugo site upon a push to your Gitlab or self hosted repository
It is important that the value of your NGINX_UNIT_HOSTS
environment variable doesn't include wildcards or regular
expressions as this value will be used by Hugo to determine the base URL of your site. Also, if the variable contains
multiple hosts (e.g., myhost.com,otherhost.com
), only the first host (the one before the ,
) will be used.
It is highly recommended that you use container orchestration software such as Docker Compose when using this NGINX Host unit as several Docker containers are required for operation. This guide will assume that you are using Docker Compose.
To begin, start with a basic docker-compose.yml
file as described in the
NGINX Host configuration guide. Then, add a
service for the NGINX Host Hugo unit (named hugo
):
hugo:
image: handcraftedbits/nginx-unit-hugo
environment:
- NGINX_UNIT_HOSTS=mysite.com
- NGINX_URL_PREFIX=/blog
- HUGO_REPO_URL=https://github.com/mysite/blog.git
- HUGO_REPO_SECRET=password
- HUGO_THEME=my_hugo_theme
volumes:
- data:/opt/container/shared
Observe the following:
- Several environment variables are used to configure Hugo. See the environment variable reference for additional information.
- As with any other NGINX Host unit, we mount our data volume, in this case named
data
, to/opt/container/shared
.
Finally, we need to create a link in our NGINX Host container to the hugo
container in order to host Hugo. Here is
our final docker-compose.yml
file:
version: "2.1"
volumes:
data:
services:
hugo:
image: handcraftedbits/nginx-unit-hugo
environment:
- NGINX_UNIT_HOSTS=mysite.com
- NGINX_URL_PREFIX=/blog
- HUGO_REPO_URL=https://github.com/mysite/blog.git
- HUGO_REPO_SECRET=password
- HUGO_THEME=my_hugo_theme
volumes:
- data:/opt/container/shared
proxy:
image: handcraftedbits/nginx-host
links:
- hugo
ports:
- "443:443"
volumes:
- data:/opt/container/shared
- /etc/letsencrypt:/etc/letsencrypt
- /home/me/dhparam.pem:/etc/ssl/dhparam.pem
This will result in making Hugo available at https://mysite.com/blog
.
The NGINX Host Hugo unit assumes that all themes are stored alongside your content in your repository. This means that
the value of the HUGO_THEME
environment variable should specify the name of a directory in your repository that
contains the Hugo theme you wish to use.
The easiest way to store your themes alongside your content is to simply copy the theme into a directory. A better approach, if the theme is available in its own Git repository, is to use a Git submodule, for example:
git submodule add user@myrepo.com:my_theme themes/my_theme
If your content repository is stored in GitHub or GitLab, your Hugo site can be automatically regenerated after a push. Simply create a GitHub webhook or a GitLab webhook for your repository with the URL
https://<host>/<prefix>/rebuild
where <host>
is your server's hostname and <prefix>
is webhooks-hugo
if the environment variable
NGINX_URL_PREFIX
is set to /
or webhooks-<sitePrefix>
if NGINX_URL_PREFIX
is set to <sitePrefix>
.
For example, if the blog is hosted at https://mysite.com/
, then the webhook URL will be
https://mysite.com/webhooks-hugo/rebuild
; if the blog is hosted at https://mysite.com/blog
(i.e.,
NGINX_URL_PREFIX
is set to /blog
), the webhook URL will be https://mysite.com/webhooks-blog/rebuild
.
You will also need to set the environment variable HUGO_REPO_SECRET
to the secret value specified during
configuration of the webhook in GitHub or GitLab.
You can run a pre-build script (for example, to copy resources before Hugo generates your site) by attaching a file to
the /opt/container/script/pre-hugo-build.sh
volume, for example:
hugo:
image: handcraftedbits/nginx-unit-hugo
environment:
- NGINX_UNIT_HOSTS=mysite.com
- NGINX_URL_PREFIX=/blog
- HUGO_REPO_URL=https://github.com/mysite/blog.git
- HUGO_REPO_SECRET=password
- HUGO_THEME=my_hugo_theme
volumes:
- data:/opt/container/shared
- /home/me/my-pre-build-script.sh:/opt/container/script/pre-hugo-build.sh
The directory where your Hugo repository has been cloned will be provided to this script as the first argument.
You can run a post-build script (for example, to minimize HTML after Hugo generates your site) by attaching a file to
the /opt/container/script/post-hugo-build.sh
volume, for example:
hugo:
image: handcraftedbits/nginx-unit-hugo
environment:
- NGINX_UNIT_HOSTS=mysite.com
- NGINX_URL_PREFIX=/blog
- HUGO_REPO_URL=https://github.com/mysite/blog.git
- HUGO_REPO_SECRET=password
- HUGO_THEME=my_hugo_theme
volumes:
- data:/opt/container/shared
- /home/me/my-post-build-script.sh:/opt/container/script/post-hugo-build.sh
The directory where your Hugo repository has been cloned will be provided to this script as the first argument.
Assuming you are using Docker Compose, simply run docker-compose up
in the same directory as your
docker-compose.yml
file. Otherwise, you will need to start each container with docker run
or a suitable
alternative, making sure to add the appropriate environment variables and volume references.
Used to ignore Hugo's cache directory (i.e., calls Hugo with the --ignoreCache
parameter) if set to true
.
Default value: false
The branch of the Git repository hosting your Hugo site.
Default value: master
The secret value used when setting up the Hugo site rebuild webhook on GitHub or GitLab.
Required
The URL of the Git repository hosting your Hugo site.
Required if your Git repository is hosted on GitHub or GitLab.
The name of the theme used to render your Hugo site.
Required
Please see the NGINX Host documentation and docker-nginx-unit-webhook documentation for information on additional environment variables understood by this unit.