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 .upstream
files 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.
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.Last modified 2yr ago