# 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.

### 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://nginxle.onepub.dev/customise-nginx-le-container.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.