Custom docker file

In some circumstances it may be required that you modify the standard Dockerfile that Nginx-LE ships with.

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/operating/defaults.conf

The nginx.conf is the first configuration file that nginx loads which then chains 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.

Otherwise you can replace the /etc/nginx/operating/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/operating/default.conf

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

If you modify the 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/operating directory.

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

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

This allows nginx to start and then nginx-le can then you can run the acquire command to obtain a valid certificate.

Its important to note here that we do this because nginx will not start if you don't have a valid certificate and it has been configured to start a HTTPS service.

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