Accommodate template inheritance for nginx confs

[fullyint]

From #688

Trellis Nginx includes have been limited to one location, inside the primary server block. This PR adds hooks to enable users to include files or inject snippets in other locations (e.g., outside server block). Here is an example of needing to inject a directive in the http context.

Whereas #688 enables the injection of snippets, this PR proposes a more powerful alternative enabling users to extend the nginx confs, overriding or augmenting any portion. This PR uses jinja template inheritance, which is probably a more proper tool for the job, and perhaps more straightforward than #688's implementation of hook variables.

Simple example

The PR's very first commit provides the easiest introduction to the concept. It is simple (4 additions and 1 deletion) and enables users to indicate a child template to use for nginx.conf. This could meet the aforementioned need to inject a directive in the http context.

The user defines the template somewhere like group_vars/all/main.yml

nginx_conf: nginx-includes/nginx.conf.child

The user creates the nginx-includes/nginx.conf.child template using jinja guidelines.

{% extends 'roles/nginx/templates/nginx.conf.j2' %}

{% block http_begin -%}
  server_names_hash_bucket_size 128;
  server_names_hash_max_size 512;
{% endblock %}

Using super()

The PR's second commit enables an example of augmenting a jinja block (vs. replacing it) by adding something additional plus the original block content via super(). Building on the example above:

  {% extends 'roles/nginx/templates/nginx.conf.j2' %}

  {% block http_begin -%}
    server_names_hash_bucket_size 128;
    server_names_hash_max_size 512;
  {% endblock %}
+ 
+ {% block sites_enabled -%}
+   # something additional
+   {{ super() }}
+ {% endblock %}

Base WordPress conf

This note from #688 still applies:

... this PR moves the base WordPress conf [wordpress.conf.j2] out of the nginx role into the wordpress-setup role. This changes this base WP conf from an include whose content is general to all sites, to content injected into each site's conf such that it can be customized per site ...

Fewer templates/includes, but still DRY

I moved the content of https.conf.j2 and wordpress_multisite_subdirectories.conf.j2 into wordpress-site.conf.j2 because block definitions enable simple DRY reuse via {{ self.https() }}. However, we could have kept these as separate templates, if that would be preferable, calling them like this:

{% block multisite_rewrites %}
{{ lookup('template', 'multisite-rewrites.conf.j2') | indent(2) }}
{% endblock -%}

{% block https %}
{{ lookup('template', 'https.conf.j2') | indent(2) -}}
{% endblock -%}

Notes

wordpress-site.conf.j2 The child template for wordpress-site.conf.j2 could be defined for all sites in group_vars/all/main.yml as well:

nginx_wordpress_site_conf: nginx-includes/wordpress-site.conf.child

This template could also vary by site, and be defined in wordpress_sites instead.

.child file extension. Child templates don't need to end in .child but that may be a helpful convention. It is better to avoid the pattern *.conf.j2, however, to avoid these templates being templated to includes.d on the server.

Indentation and formatting. The revised templating also unifies the indentation strategy in the template and finally creates perfectly formatted confs on the server (except for a blank line at end of file that is possible under some circumstances).

[nathanielks]

jinja template inheritance

😍

[swalkinshaw]

Tested this out and it works great.