Merge pull request #1255 from oxyc/templates

Allow provided templates to be extended through template inheritance

Author: geerlingguy

README.md

@@ -91,7 +91,7 @@ Note: *If there are any errors during the course of running `vagrant up`, and it
 ### 3 - Configure your host machine to access the VM.
 
   1. [Edit your hosts file](http://www.rackspace.com/knowledge_center/article/how-do-i-modify-my-hosts-file), adding the line `192.168.88.88  drupalvm.dev` so you can connect to the VM.
-    - You can have Vagrant automatically configure your hosts file if you install the `hostsupdater` plugin (`vagrant plugin install vagrant-hostsupdater`). All hosts defined in `apache_vhosts` or `nginx_hosts` will be automatically managed. `vagrant-hostmanager` is also supported.
+    - You can have Vagrant automatically configure your hosts file if you install the `hostsupdater` plugin (`vagrant plugin install vagrant-hostsupdater`). All hosts defined in `apache_vhosts` or `nginx_vhosts` will be automatically managed. `vagrant-hostmanager` is also supported.
     - The `auto_network` plugin (`vagrant plugin install vagrant-auto_network`) can help with IP address management if you set `vagrant_ip` to `0.0.0.0` inside `config.yml`.
   2. Open your browser and access [http://drupalvm.dev/](http://drupalvm.dev/). The default login for the admin account is `admin` for both the username and password.
 

default.config.yml

@@ -96,6 +96,8 @@ drupalvm_cron_jobs: []
 # Drupal VM automatically creates a drush alias file in your ~/.drush folder if
 # this variable is 'true'.
 configure_drush_aliases: true
+drush_aliases_host_template: "templates/drupalvm.aliases.drushrc.php.j2"
+drush_aliases_guest_template: "templates/drupalvm-local.aliases.drushrc.php.j2"
 
 # Helper variable to configure the PHP-FPM connection for each Apache
 # VirtualHost in the `apache_vhosts` list.
@@ -165,6 +167,7 @@ nginx_hosts:
 
 nginx_remove_default_vhost: true
 nginx_ppa_use: true
+nginx_vhost_template: "templates/nginx-vhost.conf.j2"
 
 # MySQL databases and users.
 mysql_databases:

docs/configurations/webservers-nginx.md

@@ -1,6 +1,6 @@
 To use Nginx instead of Apache, change the `drupalvm_webserver` variable inside your customized `config.yml`, from `apache` to `nginx`.
 
-Because Nginx server directives behave a little differently than Apache's VirtualHosts, Drupal VM includes a custom Drupal-optimized Nginx server block configuration, and you can control all the servers ('virtual hosts') Nginx will run using the `nginx_hosts` configuration. A few simple examples are shown in `default.config.yml`, but you have some extra flexibility if you need it. See the `nginx-vhost.conf.j2` template for more information.
+Because Nginx server directives behave a little differently than Apache's VirtualHosts, Drupal VM includes a custom Drupal-optimized Nginx server block configuration, and you can control all the servers ('virtual hosts') Nginx will run using the `nginx_vhosts` configuration. A few simple examples are shown in `default.config.yml`, but you have some extra flexibility if you need it. See the `nginx-vhost.conf.j2` template for more information.
 
 Also, see the examples included in the [`geerlingguy.nginx` Ansible role's README](https://github.com/geerlingguy/ansible-role-nginx#readme) for more info, as well as many other variables you can override to configure Nginx exactly how you like it.
 
@@ -10,7 +10,7 @@ _Note: if you're using php-fpm, you may want to reflect your use of nginx by set
 
 To enable SSL support for you virtual hosts you first need a certificate file. See the same section under the [Apache documentation](webservers-apache.md#enable-ssl-support-with-apache) for how to generate a self-signed certficiate.
 
-Modify your nginx host configuration by adding the following `extra_parameters` to the first entry in `nginx_hosts`:
+Modify your nginx host configuration by adding the following `extra_parameters` to the first entry in `nginx_vhosts`:
 
 ```yaml
 - server_name: "{{ drupal_domain }} www.{{ drupal_domain }}"
@@ -39,3 +39,43 @@ If you are using Ubuntu as your base OS and you want to get started quickly with
         ssl_protocols       TLSv1.1 TLSv1.2;
         ssl_ciphers         HIGH:!aNULL:!MD5;
 ```
+
+## Customizing server block configuration
+
+If you can't customize via variables because an option isn't exposed, you can override the template used to generate the the virtualhost configuration file.
+
+```yaml
+nginx_vhost_template: "{{ config_dir }}/templates/nginx-vhost.conf.j2"
+```
+
+You can either copy and modify the provided `nginx-vhost.conf.j2` template, or extend it and use [template inheritace](http://jinja.pocoo.org/docs/2.9/templates/#template-inheritance) to override the specific template block you need to change.
+
+_If you extend Drupal VM's provided base template, the path referenced should to be relative to playbook.yml._
+
+```
+{% extends 'templates/nginx-vhost.conf.j2' %}
+
+{% block location_primary %}
+location / {
+    try_files $uri @rewrite; # For Drupal <= 6
+}
+{% endblock %}
+
+{% block location_image_styles %}
+location ~ ^/sites/.*/files/imagecache/ {
+    try_files $uri @rewrite; # For Drupal <= 6
+}
+{% endblock %}
+```
+
+If you need to append or prepend content to a block, you can use the `{{ super() }}` Jinja2 function to return the original block content from the base template.
+
+```
+{% block location_deny %}
+{{ super() }}
+location ~* \.(txt|log)$ {
+    allow 192.168.0.0/16;
+    deny all;
+}
+{% endblock %}
+```

docs/deployment/multisite.md

@@ -1,4 +1,4 @@
-For multisite installations, make the changes outlined in the [Local Drupal codebase](local-codebase.md) guide, but, using the `apache_vhosts` variable (or `nginx_hosts` if using Nginx), configure as many domains pointing to the same docroot as you need:
+For multisite installations, make the changes outlined in the [Local Drupal codebase](local-codebase.md) guide, but, using the `apache_vhosts` variable (or `nginx_vhosts` if using Nginx), configure as many domains pointing to the same docroot as you need:
 
 ```yaml
 drupal_core_path: "/var/www/my-drupal-site"

docs/extras/drush.md

@@ -35,6 +35,22 @@ $ drush @drupalvm.dev status
 
 Drupal VM automatically generates a drush alias file in `~/.drush/drupalvm.aliases.drushrc.php` with an alias for every site you have defined in the `apache_vhosts` variable.
 
+If you want to customize the generated alias file you can override the `drush_aliases_host_template` and `drush_aliases_guest_template` variables in your `config.yml`.
+
+```yaml
+drush_aliases_host_template: "{{ config_dir }}/templates/drupalvm.aliases.drushrc.php.j2"
+```
+
+Eg. to only print the alias for your main domain, and not the subdomain you can override the file using a [Jinja2 child template](http://jinja.pocoo.org/docs/2.9/templates/#child-template).
+
+```php
+{% extends 'templates/drupalvm.aliases.drushrc.php.j2' %}
+
+{% block aliases %}
+{{ alias('drupalvm.dev', drupal_core_path) }}
+{% endblock %}
+```
+
 You can disable Drupal VM's automatic Drush alias file management if you want to manage drush aliases on your own. Just set the `configure_drush_aliases` variable in `config.yml` to `false`.
 
 ## Using sql-sync

docs/extras/varnish.md

@@ -31,4 +31,34 @@ $settings['reverse_proxy_addresses'] = array('127.0.0.1');
 
 If you don't set these values, Drupal will think all requests are coming from `127.0.0.1`. There are other settings you can change to make Drupal not store copies of cached pages in the Database (since Varnish is caching everything, this is redundant), but those other settings are not covered here.
 
+## Extending the base `drupalvm.vcl.j2` template
+
+If you can't customize via variables because an option isn't exposed, you can extend the base `drupalvm.vcl.j2` through [Jinja2 template inheritance](http://jinja.pocoo.org/docs/2.9/templates/#template-inheritance).
+
+```yaml
+varnish_default_vcl_template_path: "{{ config_dir }}/templates/drupalvm.vcl.j2"
+```
+
+Either copy the `drupalvm.vcl.j2` and modify it to your liking, or extend it and override the blocks you need to adjust.
+
+_If you extend Drupal VM's provided base template, the path referenced should to be relative to playbook.yml._
+
+```
+{% extends 'templates/drupalvm.vcl.j2' %}
+
+{% block backend -%}
+{{ super() }}
+.connect_timeout = 1s;
+{% endblock %}
+
+{% block vcl_deliver -%}
+unset resp.http.X-Url;
+unset resp.http.X-Host;
+unset resp.http.Purge-Cache-Tags;
+# Do not set X-Varnish-Cache headers.
+{% endblock %}
+```
+
+The [`{{ super() }}` Jinja2 function](http://jinja.pocoo.org/docs/2.9/templates/#super-blocks) returns the original block content from the base template.
+
 For a list of available role variables, see the [`geerlingguy.varnish` Ansible role's README](https://github.com/geerlingguy/ansible-role-varnish#readme).

examples/prod/prod.config.yml

@@ -3,7 +3,7 @@
 drupal_domain: "drupalvm.dev"
 vagrant_hostname: "{{ drupal_domain }}"
 
-# Add only the `apache_vhosts` or `nginx_hosts` you need. If installing a
+# Add only the `apache_vhosts` or `nginx_vhosts` you need. If installing a
 # single Drupal site, the variable should look like this (Apache):
 apache_vhosts:
   - servername: "{{ drupal_domain }}"

lib/drupalvm/vagrant.rb

@@ -95,7 +95,8 @@ def get_vhost_aliases(vconfig)
   if vconfig['drupalvm_webserver'] == 'apache'
     aliases = get_apache_vhosts(vconfig['apache_vhosts'])
   else
-    aliases = get_nginx_vhosts(vconfig['nginx_hosts'])
+    # @todo shim for `nginx_hosts`.
+    aliases = get_nginx_vhosts(vconfig.fetch('nginx_hosts', vconfig['nginx_vhosts']))
   end
   aliases = aliases.uniq - [vconfig['vagrant_ip']]
   # Remove wildcard subdomains.

provisioning/playbook.yml

@@ -10,6 +10,10 @@
     - include: tasks/config.yml
       tags: ['always']
 
+    - include: tasks/backwards-compatibility.yml
+      tags: ['always']
+      static: no
+
     - include: "tasks/init-{{ ansible_os_family }}.yml"
       static: no
 

provisioning/roles/drupalvm.www/tasks/main.yml

@@ -85,15 +85,3 @@
     mode: 0755
     recurse: true
   when: drupalvm_webserver == 'apache'
-
-- name: Copy Nginx vhosts into place.
-  template:
-    src: ../templates/nginx-vhost.conf.j2
-    dest: "{{ nginx_vhost_path }}/{{ item.server_name.split(' ')[0] }}.conf"
-    force: yes
-    owner: root
-    group: root
-    mode: 0644
-  with_items: "{{ nginx_hosts }}"
-  notify: restart nginx
-  when: drupalvm_webserver == 'nginx'

provisioning/tasks/backwards-compatibility.yml

@@ -0,0 +1,5 @@
+---
+- name: nginx_hosts shim
+  set_fact:
+    nginx_vhosts: "{{ nginx_hosts }}"
+  when: nginx_hosts is defined

provisioning/tasks/drush-aliases.yml

@@ -18,7 +18,7 @@
 # Note that this doesn't work for Windows, since Ansible's running in the VM.
 - name: Configure host machine drush aliases.
   template:
-    src: ../templates/drupalvm.aliases.drushrc.php.j2
+    src: "{{ drush_aliases_host_template }}"
     dest: "~/.drush/{{ vagrant_machine_name }}.aliases.drushrc.php"
   delegate_to: 127.0.0.1
   become: no
@@ -30,7 +30,7 @@
 
 - name: Configure drush aliases for vagrant user inside VM.
   template:
-    src: ../templates/drupalvm-local.aliases.drushrc.php.j2
+    src: "{{ drush_aliases_guest_template }}"
     dest: "~/.drush/{{ vagrant_machine_name }}.aliases.drushrc.php"
   become: no
   when: configure_drush_aliases
@@ -40,6 +40,6 @@
 
 - name: Configure drush aliases for root user inside VM.
   template:
-    src: ../templates/drupalvm-local.aliases.drushrc.php.j2
+    src: "{{ drush_aliases_guest_template }}"
     dest: "~/.drush/{{ vagrant_machine_name }}.aliases.drushrc.php"
   when: configure_drush_aliases

provisioning/templates/dashboard.html.j2

@@ -33,7 +33,7 @@
           {%- endif -%}
         {%- endfor -%}
       {%- elif drupalvm_webserver == 'nginx' -%}
-        {%- for host in nginx_hosts -%}
+        {%- for host in nginx_vhosts -%}
           {%- if host.root == path -%}
             {{ host.server_name }}
           {%- endif -%}
@@ -73,7 +73,7 @@
 
           {%- endfor -%}
         {%- elif drupalvm_webserver == 'nginx' -%}
-          {%- for host in nginx_hosts -%}
+          {%- for host in nginx_vhosts -%}
 
             {% for server_name in host.server_name.split(' ') -%}
               {{ printHostsEntry(vagrant_ip, server_name) }}
@@ -107,7 +107,7 @@
               {%- endif -%}
             {%- endfor -%}
           {%- elif drupalvm_webserver == 'nginx' -%}
-            {%- for host in nginx_hosts -%}
+            {%- for host in nginx_vhosts -%}
               {%- if host.root is defined -%}
                 {%- for hostname in host.server_name.split() -%}
                   {{ printSite(hostname, host.root) }}

provisioning/templates/drupalvm-local.aliases.drushrc.php.j2

@@ -6,16 +6,17 @@
  * @see example.aliases.drushrc.php.
  */
 
-{% macro alias(host, root) %}
+{% macro alias(host, root) -%}
 {%- if root not in _devtool_docroots %}
 $aliases['{{ host }}'] = array(
   'uri' => '{{ host }}',
   'root' => '{{ root }}',
 );
 
 {% endif -%}
-{% endmacro %}
+{% endmacro -%}
 
+{% block aliases -%}
 {%- if drupalvm_webserver == 'apache' -%}
   {%- for vhost in apache_vhosts -%}
     {{ alias(vhost.servername, vhost.documentroot) }}
@@ -26,9 +27,10 @@ $aliases['{{ host }}'] = array(
     {%- endif -%}
   {%- endfor -%}
 {%- elif drupalvm_webserver == 'nginx' -%}
-  {%- for host in nginx_hosts -%}
+  {%- for host in nginx_vhosts -%}
     {%- for server_name in host.server_name.split() -%}
       {{ alias(server_name, host.root) }}
     {%- endfor -%}
   {%- endfor -%}
 {%- endif -%}
+{%- endblock %}

provisioning/templates/drupalvm.aliases.drushrc.php.j2

@@ -6,7 +6,7 @@
  * @see example.aliases.drushrc.php.
  */
 
-{% macro alias(host, root) %}
+{% macro alias(host, root) -%}
 {%- if root not in _devtool_docroots %}
 $aliases['{{ host }}'] = array(
   'uri' => '{{ host }}',
@@ -20,8 +20,9 @@ $aliases['{{ host }}'] = array(
 );
 
 {% endif -%}
-{% endmacro %}
+{% endmacro -%}
 
+{% block aliases -%}
 {%- if drupalvm_webserver == 'apache' -%}
   {%- for vhost in apache_vhosts -%}
     {{ alias(vhost.servername, vhost.documentroot) }}
@@ -32,9 +33,10 @@ $aliases['{{ host }}'] = array(
     {%- endif -%}
   {%- endfor -%}
 {%- elif drupalvm_webserver == 'nginx' -%}
-  {%- for host in nginx_hosts -%}
+  {%- for host in nginx_vhosts -%}
     {%- for server_name in host.server_name.split() -%}
       {{ alias(server_name, host.root) }}
     {%- endfor -%}
   {%- endfor -%}
 {%- endif -%}
+{%- endblock %}