Customise Nginx-le container

In some circumstances it may be required that you modify the standard Nginx-LE docker container.

This section details the internal structure of the docker image and what the hard requirements are.

By default the Nginx-LE ships with the following configuration files:

The base nginx configuration is defined by:

• /etc/nginx/nginx.conf

• /etc/nginx/custom/defaults.conf

The nginx.conf is the first configuration file that nginx loads which then chain loads the default.conf file which in turn loads our standard .location and .upstream files.

If you are happy with the standard configuration you can simply add .location and .upstreamfiles under /opt/nginx/include which is normally done via a persistent volume but you could directly include these files in your own custom nginx-le container.

You can also replace the /etc/nginx/custom/default.conf with your own customised defaults.

NOTE: if you replace default.conf you MUST include a ./well-known location for lets-encrypt to work:

  # lets encrypt renewal path
    location ^~ /.well-known {
      allow all;
      root  /opt/letsencrypt/wwwroot;
    }

The nginx-le container REQUIRES that you have a default.conf file in:

• /etc/nginx/custom/default.conf

If you need complete control over nginx then you can also replace the /etc/nginx/nginx.conf file.

If you modify the /etc/nginx/nginx.conf it must include the following lines:

• daemon off;

• user nginx;

• include /etc/nginx/live/default.conf

Changing any of the above settings will cause nginx-le to fail.

What's with this 'live' directory

The nginx.conf loads its configuration from the /etc/nginx/live/defaults.conf file.

However the above instructions dictate that you put your default.conf in /etc/nginx/operating/defaults.conf

Note: the difference operating vs live.

At runtime Nginx-LE pulls its configuration from the live directory.

On startup, if you have a valid certificate, the live directory is symlinked to your /etc/nginx/custom directory.

If you don't have a valid certificate, the live directory is symlinked to the /etc/nginx/acquire folder and Nginx-LE is placed into acquisition mode.

The acquire path contains a single index.html page informing users that a certificate needs to be acquired. In this mode no other content will be served and only requests from certbot will be processed.

Normally nginx-le will initially start in the acquire mode whilst it acquires a certificate for the first time. Once it has acquired a certificate then transitions to its standard operating mode.

If you have configured nginx-le to not auto acquire a certificate it stays in this mode until you run nginx-le acquire.

It's important to note here that we do this because when nginx has been configured to start an HTTPS service, nginx will not start if you don't have a valid certificate. The acquisition mode starts nginx as an HTTP only service to avoid nginx shutting down.

Once a valid certificate has been acquired nginx-le switches the live symlink back to /etc/nginx/custom and does a nginx reload and your site is online.