Merge pull request #92 from oxyc/template-inheritance

Template inheritance

README.md

@@ -121,6 +121,58 @@ Configures Nginx's [`log_format`](http://nginx.org/en/docs/http/ngx_http_log_mod
 
 (For RedHat/CentOS only) Set this to `false` to disable the installation of the `nginx` yum repository. This could be necessary if you want the default OS stable packages, or if you use Satellite.
 
+## Overriding configuration templates
+
+If you can't customize via variables because an option isn't exposed, you can override the template used to generate the virtualhost configuration files or the `nginx.conf` file.
+
+```yaml
+nginx_conf_template: "nginx.conf.j2"
+nginx_vhost_template: "vhost.j2"
+```
+
+You can either copy and modify the provided template, or extend it with [Jinja2 template inheritance](http://jinja.pocoo.org/docs/2.9/templates/#template-inheritance) and override the specific template block you need to change.
+
+### Example: Configure gzip in nginx configuration
+
+Set the `nginx_conf_template` to point to a template file in your playbook directory.
+
+```yaml
+nginx_conf_template: "{{ playbook_dir }}/templates/nginx.conf.j2"
+```
+
+Create the child template in the path you configured above and extend `geerlingguy.nginx` template file relative to your `playbook.yml`.
+
+```
+{% extends 'roles/geerlingguy.nginx/templates/nginx.conf.j2' %}
+
+{% block http_gzip %}
+    gzip on;
+    gzip_proxied any;
+    gzip_static on;
+    gzip_http_version 1.0;
+    gzip_disable "MSIE [1-6]\.";
+    gzip_vary on;
+    gzip_comp_level 6;
+    gzip_types
+        text/plain
+        text/css
+        text/xml
+        text/javascript
+        application/javascript
+        application/x-javascript
+        application/json
+        application/xml
+        application/xml+rss
+        application/xhtml+xml
+        application/x-font-ttf
+        application/x-font-opentype
+        image/svg+xml
+        image/x-icon;
+    gzip_buffers 16 8k;
+    gzip_min_length 512;
+{% endblock %}
+```
+
 ## Dependencies
 
 None.

defaults/main.yml

@@ -12,6 +12,9 @@ nginx_ppa_version: stable
 # The name of the nginx apt/yum package to install.
 nginx_package_name: "nginx"
 
+nginx_conf_template: "nginx.conf.j2"
+nginx_vhost_template: "vhost.j2"
+
 nginx_worker_processes: "{{ ansible_processor_vcpus | default(ansible_processor_count) }}"
 nginx_worker_connections: "1024"
 nginx_multi_accept: "off"

tasks/main.yml

@@ -30,7 +30,7 @@
 # Nginx setup.
 - name: Copy nginx configuration in place.
   template:
-    src: nginx.conf.j2
+    src: "{{ nginx_conf_template }}"
     dest: "{{ nginx_conf_file_path }}"
     owner: root
     group: "{{ root_group }}"

tasks/vhosts.yml

@@ -14,7 +14,7 @@
 
 - name: Add managed vhost config files.
   template:
-    src: vhost.j2
+    src: "{{ nginx_vhost_template }}"
     dest: "{{ nginx_vhost_path }}/{{ item.server_name.split(' ')[0] }}.conf"
     force: yes
     owner: root

templates/nginx.conf.j2

@@ -3,18 +3,25 @@ user  {{ nginx_user }};
 error_log  {{ nginx_error_log }};
 pid        {{ nginx_pidfile }};
 
+{% block worker %}
 worker_processes  {{ nginx_worker_processes }};
+{% endblock %}
 
+{% block events %}
 events {
     worker_connections  {{ nginx_worker_connections }};
     multi_accept {{ nginx_multi_accept }};
 }
+{% endblock %}
 
 {% if nginx_extra_conf_options %}
 {{ nginx_extra_conf_options }}
 {% endif %}
 
 http {
+    {% block http_begin %}{% endblock %}
+
+{% block http_basic %}
     include       {{ nginx_mime_file_path }};
     default_type  application/octet-stream;
 
@@ -34,16 +41,20 @@ http {
     keepalive_requests {{ nginx_keepalive_requests }};
 
     server_tokens {{ nginx_server_tokens }};
-    #gzip  on;
-
 {% if nginx_proxy_cache_path %}
     proxy_cache_path {{ nginx_proxy_cache_path }};
 {% endif %}
+{% endblock %}
+
+{% block http_gzip %}
+    # gzip on;
+{% endblock %}
 
 {% if nginx_extra_http_options %}
     {{ nginx_extra_http_options|indent(4, False) }}
 {% endif %}
 
+{% block http_upstream %}
 {% for upstream in nginx_upstreams %}
     upstream {{ upstream.name }} {
 {% if upstream.strategy is defined %}
@@ -57,9 +68,14 @@ http {
 {% endif %}
     }
 {% endfor %}
+{% endblock %}
 
+{% block http_includes %}
     include {{ nginx_conf_path }}/*.conf;
 {% if nginx_conf_path != nginx_vhost_path %}
     include {{ nginx_vhost_path }}/*;
 {% endif %}
+{% endblock %}
+
+    {% block http_end %}{% endblock %}
 }

templates/vhost.j2

@@ -1,4 +1,16 @@
+{% block server_redirect %}
+{% if item.server_name_redirect is defined %}
+    listen       {{ item.listen | default('80') }};
+    server_name  {{ item.server_name_redirect }};
+    return       301 $scheme://{{ item.server_name.split(' ')[0] }}$request_uri;
+}
+{% endif %}
+{% endblock %}
+
 server {
+    {% block server_begin %}{% endblock %}
+
+    {% block server_basic -%}
     listen {{ item.listen | default('80') }};
 
 {% if item.server_name is defined %}
@@ -24,6 +36,9 @@ server {
 {% if item.return is defined %}
     return {{ item.return }};
 {% endif %}
+    {% endblock %}
+
+    {% block server_end %}{% endblock %}
 
 {% if item.extra_parameters is defined %}
     {{ item.extra_parameters|indent(4) }}