nginx-le
Search…
Overview
Prerequisites
Cli commands
docker-compose
Certificate management
Customise Nginx-le container
Diagnosing problems
Environment variables
Contributing
Custom Content Providers
Custom docker file
Auth Providers
Powered By GitBook
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.

​

Previous
Custom Content Providers
Next
Auth Providers
Last modified 1yr ago
Copy link
Outline
What's with this 'live' directory