> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipways.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Nginx configuration and templates

> What Shipways writes for you, what you can add, and what you can take over.

Shipways owns each site's server block and rewrites it whenever the domains,
the web directory, the PHP version or the certificate move. It checks the
configuration before reloading, so anything nginx refuses leaves the running
config alone.

There are three levels of taking it over.

## Extra directives

A box on the site's settings for additions to **this site's** server block, on
top of whatever template it uses:

```nginx theme={null}
client_max_body_size 64m;
```

Emptying it puts the site back to the default. This is the right level for
one-off directives on one site.

## Routing templates

How a *kind* of site routes requests, written once and shared across sites.

A routing template is the `location` blocks and nothing else. Shipways writes
the TLS, the certificate challenge, the password prompt and the redirects
around it — the parts a site can be got badly wrong on stay outside a template
and are Shipways' to get right once.

Every site starts on the built-in template, which is what a Laravel application
needs.

Available tokens:

| Token         | What it stands for                                         |
| ------------- | ---------------------------------------------------------- |
| `DOMAIN`      | The site's primary domain.                                 |
| `ROOT`        | The directory nginx serves, through the `current` symlink. |
| `SITE_PATH`   | The site's directory on the machine.                       |
| `PHP_SOCKET`  | This site's FPM socket.                                    |
| `PHP_VERSION` | The site's PHP version.                                    |
| `PROXY_PORT`  | The port, for a proxied site.                              |

Nothing in a template runs. It is text with holes in it, and the tokens are an
allow-list.

## Whole-block templates

The whole file. Use one when you need something the routing half cannot
express: another port, extra server blocks, TLS terms of your own.

Every managed piece is offered as a token on top of the ones above, so a
template that wants the usual TLS or the usual challenge location asks for it
rather than copying it and letting the copy go stale:

`SERVER_NAME`, `LISTEN`, `TLS`, `ACME_CHALLENGE`, `BASIC_AUTH`,
`MAINTENANCE`, `REDIRECTS`, `HTTP_REDIRECT_BLOCK`, `ACCESS_LOG`, `ERROR_LOG`,
`CUSTOM_CONFIG`.

<Warning>
  What a whole-block template leaves out is left out. Drop `ACME_CHALLENGE` and
  [certificate renewal](/sites/certificates#renewal) stops working. Drop
  `MAINTENANCE` and [maintenance mode](/sites/maintenance) does nothing. Drop
  `BASIC_AUTH` and the [password prompt](/sites/security) is gone.

  Start from the offered starter rather than a blank box; it renders what
  Shipways would have written, so you are editing something that already works.
</Warning>

## Removing a template

Sites using it go back to the built-in template and are rewritten. The panel
says how many before you confirm.