Skip to content


The Lagoon nginx image Dockerfile. Based on the official openresty/openresty images.

This Dockerfile is intended to be used as a base for any web servers within Lagoon.

Lagoon adaptions#

The default exposed port of nginx containers is port 8080.

This image is prepared to be used on Lagoon. There are therefore some things already done:

  • Folder permissions are automatically adapted with fix-permissions, so this image will work with a random user.
  • The files within /etc/nginx/* are parsed through envplate with a container-entrypoint.

Included NGINX configuration (static-files.conf)#


By default NGINX only serves static files - this can be used for static sites that don't require a database or PHP components: for example, static site generators like Hugo, Jekyll or Gatsby.

If you need PHP, have a look at the php-fpm image and use nginx and php-fpm in tandem.

Build the content during the build process and inject it into the nginx container.



In order to create redirects, we have redirects-map.conf in place. This helps you to redirect marketing domains to sub-sites or do non-www to www redirects. If you have a lot of redirects, we suggest having redirects-map.conf stored next to your code for easier maintainability.


If you only have a few redirects, there's a handy trick to create the redirects with a RUN command in your nginx.dockerfile.

Here's an example showing how to redirect to and preserve the request:

RUN echo "~^\$request_uri;" >> /etc/nginx/redirects-map.conf

To get more details about the various types of redirects that can be achieved, see the documentation within the redirects-map.conf directly.

After you put the redirects-map.conf in place, you also need to include it in your nginx.dockerfile in order to get the configuration file into your build.

COPY redirects-map.conf /etc/nginx/redirects-map.conf

Basic Authentication#

If you want to protect your site via basic authentication, you can do this by defining the environment variables BASIC_AUTH_USERNAME and BASIC_AUTH_PASSWORD within your .lagoon.env.environment files. For further explanation on how to set up Environment Variables on Lagoon, check here.

Environment Variables#

Environment variables are meant to contain common information for the nginx container.

Environment Variable Default Description
BASIC_AUTH restricted By not setting BASIC_AUTH this will instruct Lagoon to automatically enable basic authentication if BASIC_AUTH_USERNAME and BASIC_AUTH_PASSWORD are set. To disable basic authentication even if BASIC_AUTH_USERNAME and BASIC_AUTH_PASSWORD are set, set BASIC_AUTH to off.
BASIC_AUTH_USERNAME (not set) Username for basic authentication
BASIC_AUTH_PASSWORD (not set) Password for basic authentication (unencrypted)
FAST_HEALTH_CHECK (not set) If set to true this will redirect GET requests from certain user agents (StatusCake, Pingdom, Site25x7, Uptime, nagios) to the lightweight Lagoon service healthcheck.