Customise Nginx with templates

Every site SrvYard creates gets an Nginx configuration generated from the site's domains, PHP version and certificate. For most applications that is exactly right. When you need something different for every site on a server, such as larger uploads, extra security headers or a custom cache rule, you do not edit generated files by hand. You write a template: one server { } block with variables, saved on the server, and chosen when you create a site or in the site's Nginx settings.

Templates belong to a single server. Changing or deleting a template never touches sites that already use it, so you can experiment safely.

Before you begin#

• A server that runs Nginx. App, web and load balancer servers have the Nginx tab; database and cache servers do not.
• A role that can manage the server. Without it the tab is read-only.
• Some Nginx knowledge. SrvYard validates the syntax with Nginx itself, but it cannot tell you whether the rules do what you want. Try a new template on a staging site first.

1. Open the Nginx tab#

Open the server and choose Nginx. The page, Nginx templates, explains that templates customise the Nginx configuration of sites you create on this server.

1. Add template. Opens the editor for a new one. A Copy from another server button appears next to it when other servers in the organisation already have templates.
2. A template. Shows its name, how many lines it has, Used by (how many sites use it) and when it was Updated.
3. Row actions. Edit and Delete.

2. Write a template#

Press Add template. The editor holds the text of one server { } block. SrvYard adds Let's Encrypt's challenge location and the certificate settings itself when a certificate is installed, so you do not write those.

1. Name. Shown in the list and in site settings, for example Laravel with long uploads.
2. Content. A code editor with line numbers. It starts with SrvYard's standard Laravel-style block, so change only what you need. For long uploads that is the client_max_body_size line (for example 64m), and PHP must allow the same size in its own settings (see PHP extensions and php.ini settings).
3. Variables. Click one to copy it. Each is replaced with the value of the site when its Nginx file is written. The important ones: {{DOMAINS}} (the domain names, space separated, for server_name), {{PORT}} and {{PORT_V6}} (the listen ports for HTTP, and the HTTPS copy), {{PATH}} and {{ROOT_PATH}} (the site directory and the directory Nginx serves), {{DIRECTORY}}, {{SITE}}, {{SITE_ID}} (used in log file names), {{USER}}, {{PROXY_PASS}} (for proxied apps), {{SERVER_PUBLIC_IP}}, {{SERVER_PRIVATE_IP}}, {{PHP_SOCKET}} and {{PHP_VERSION}}.
4. Restore default. Replaces the editor content with SrvYard's standard template.
5. Check with Nginx. Validates without saving.
6. Create template (or Save when editing). Saves, after validating.

What the check does#

Before a template is saved, SrvYard checks that it is not empty, is under the size limit, uses only known variables, contains {{DOMAINS}} and {{PORT}} and is a single server { } block. It then renders a sample and has Nginx on the server test it with nginx -t on a throw-away file, so the running configuration is never touched. Errors appear under the editor, for example "Unknown variable" with the name.

3. Use the template for a site#

On the Create site form, a Nginx template menu appears when the chosen server has templates. It starts at Standard configuration. Choose your template to generate the site's file from it.

1. Nginx template. The menu, with the hint "Templates are managed on the server's Nginx tab." Your templates are listed under Standard configuration once you open it.

For a site that already exists, open the site's Settings tab and use the Template menu in the Nginx configuration card. Switching it rebuilds the site's Nginx file from the chosen template; the menu is disabled while the site uses a hand-edited custom configuration.

4. Edit, copy and delete templates#

1. Edit. Opens the same editor. Saving does not change the Nginx files of sites that already use the template. They pick up the new text the next time their configuration is rebuilt.
2. Delete. Asks for confirmation. If sites use it, they keep their current Nginx file and fall back to the standard configuration the next time it is rebuilt. With no users it simply says it cannot be undone.

Copy from another server lets you pick a template from another server and copy it here, so a tested template can be reused across a fleet.

5. Good to know#

Templates are a text file with variables, so they are easy to review and share. Keep the changes small: start from the default, change one thing, check it, save it and test it on a staging site. Name templates after what they change (Long uploads, Static assets cache) rather than after the site that first needed them, so teammates can pick the right one without asking. If a template is only needed for one site, consider whether a site-level setting such as a redirect or Basic Auth rule does the job instead, since those need no Nginx knowledge. Because templates are stored per server, copy a proven template to a new server with Copy from another server instead of retyping it.

An example: larger uploads#

Start from the default template and change one line. Find client_max_body_size and set it to the size you need, for example client_max_body_size 64m;. Press Check with Nginx, save the template as Laravel with long uploads and choose it for a new site. Then raise PHP's upload_max_filesize and post_max_size to at least the same value, because whichever limit is lowest wins. Upload a file just under the limit and one just over it to confirm the behaviour: the larger one should be refused with a 413 error from Nginx, not a timeout from PHP.

Troubleshooting#

• "The template must use {{DOMAINS}}" (or {{PORT}}). These two variables are required, since without them Nginx would not know which names or ports to serve.
• "Unknown variable". A variable name is misspelt or does not exist. The valid ones are listed beside the editor.
• Nginx rejects the template. The message from nginx -t appears under the editor. Fix the directive it names and check again.
• My change did not reach an existing site. Existing sites keep their file. Rebuild the site's configuration, or switch its template in Settings.
• 413 Request Entity Too Large on uploads. client_max_body_size in the template (and PHP's upload_max_filesize and post_max_size) must be larger than the file.
• The template menu is missing on the site form. The chosen server has no templates yet.

Related#

• Create a site on your server: where the template menu appears.
• Redirects, Basic Auth and security rules: site-level rules that do not need a template.
• 502 Bad Gateway: when Nginx cannot reach PHP.
• Manage services and restarts: reload Nginx and edit its main configuration.