# 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 `.upstream`files 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.

##