Nginx Includes

The Nginx site conf generated by Trellis is designed to work with a wide range of WordPress installations, but your sites may require additional, specific tweaks. For example, perhaps you use custom rewrites to redirect legacy URLs, or maybe you'd like to proxy some requests to another server.

Trellis (specifically the wordpress-setup role) provides a way for you to supply these tweaks as Nginx include files, without modifying the playbook. Here's how it works:

Let's say you have two sites managed by Trellis and defined in wordpress_sites, e.g.:

wordpress_sites:
  site1:
    ...
  site2:
    ...

Implement your customizations as modular Nginx include files and put them the templates folder of the wordpress-setup role, following the example directory structure below. Each file is an Ansible/Jinja2 template and can make full use of logic and variables.

roles/
  wordpress-setup/
    templates/
      includes.d/
        site1/
          rewrites.conf.j2
          proxy.conf.j2
        site2/
          rewrites.conf.j2

Note that the directory must be named includes.d and its subdirectories must match keys defined in wordpress_sites. Additionally, the files therein must end in .conf.j2—otherwise they'll be ignored.

After the playbook runs, the above playbook structure will result in the following structure on the remote machine:

/
  etc/
    nginx/
      includes.d/
        site1/
          rewrites.conf
          proxy.conf
        site2/
          rewrites.conf

These Nginx include files will be automatically included by the corresponding Nginx site conf.

If you want to edit, add to, or delete your Nginx include files, edit them on the local machine and re-run the playbook.

This feature was made possible thanks to @chriszarate in #242.