Add all files needed to bring up VM and run agaric.com locally

box/docs/extras/adminer.md

@@ -0,0 +1,3 @@
+If you have `adminer` listed as one of the `installed_extras` inside `config.yml`, you can use Adminer's web-based interface to interact with databases. With Drupal VM running, visit [http://adminer.drupalvm.test/](http://adminer.drupalvm.test/), and log in with `drupal` as the username and the password you set in `config.yml` (`drupal_db_password`). Leave the "Server" field blank. The "Database" field is optional.
+
+For a list of available role variables, see the [`geerlingguy.adminer` Ansible role's README](https://github.com/geerlingguy/ansible-role-adminer#readme).

box/docs/extras/blackfire.md

@@ -0,0 +1,23 @@
+[Blackfire.io](https://blackfire.io/) is a service that allows code profiling to be stored and analyzed via an online profile on the Blackfire.io website.
+
+It doesn't require any additional Drupal modules to use, but once you've made sure `blackfire` is in the list of `installed_extras` in `config.yml` (and Drupal VM has been provisioned), you need to log into Drupal VM and [run the setup steps outlined on the Blackfire Ansible role's README](https://github.com/geerlingguy/ansible-role-blackfire#requirements).
+
+**Note**: You should only enable one code profiler at a time—e.g. when using [Blackfire](blackfire.md), disable [XHProf](xhprof.md), [Tideways](tideways.md) and [XDebug](xdebug.md).
+
+Once you've configured your environment for your own Blackfire account, you can profile a request with Blackfire by running something like the following example (within Drupal VM, after logging in with `vagrant ssh`):
+
+```
+$ blackfire curl http://drupalvm.test/
+Profiling: [########################################] 10/10
+Blackfire cURL completed
+Graph URL https://blackfire.io/profiles/[UUID]/graph
+
+Wall Time     151ms
+CPU Time      130ms
+I/O Time     20.9ms
+Memory        1.5MB
+Network         n/a     n/a       -
+SQL             n/a       -
+```
+
+For a list of available role variables, see the [`geerlingguy.blackfire` Ansible role's README](https://github.com/geerlingguy/ansible-role-blackfire#readme).

box/docs/extras/drupal-console.md

@@ -0,0 +1,60 @@
+[Drupal Console](https://drupalconsole.com/) is a modern CLI for interacting with Drupal and scaffolding a site. It works only with Drupal 8+, and is built on top of the Symfony Console component.
+
+To have Drupal Console installed globally inside Drupal VM, make sure `drupalconsole` is in the list of `installed_extras` in your `config.yml` file. If you're adding it to an existing Drupal VM, run `vagrant provision` so it gets installed. You also (or instead) might want to add Drupal Console as a dependency of your Drupal project—if you do this, you may not need to add `drupalconsole` to Drupal VM globally.
+
+To use Drupal Console with a Drupal 8 site (in this case, using the default configuration that ships with Drupal VM):
+
+  1. Log into the VM with `vagrant ssh`.
+  2. Change directory to the Drupal site's document root: `cd /var/www/drupalvm/drupal/web`.
+  3. Use Drupal console (e.g. `drupal cache:rebuild all`).
+
+You should see an output like:
+
+```
+vagrant@drupalvm:/var/www/drupalvm/drupal/web$ drupal cache:rebuild all
+
+[+] Rebuilding cache(s), wait a moment please.
+[+] Done clearing cache(s).
+
+ The command was executed successfully!
+```
+
+## Remote command execution using `--target`
+
+To run commands on your host computer but execute them on the VM, add a new sites file `~/.console/sites/drupalvm.yml` on your host computer:
+
+```yaml
+dev:
+  root: /var/www/drupalvm/drupal
+  host: 192.168.88.88
+  user: vagrant
+  password: vagrant
+```
+
+Execute from host machine using the `--target` option.
+
+    drupal --target=drupalvm.test site:status
+
+For more details, see [Drupal Console's documentation](https://docs.drupalconsole.com/en/alias/how-to-use-drupal-console-in-a-remote-installation.html)
+
+For a list of available role variables, see the [`geerlingguy.drupal-console` Ansible role's README](https://github.com/geerlingguy/ansible-role-drupal-console#readme).
+
+## Remote command execution using `vagrant-exec`
+
+You can use [`vagrant-exec`](https://github.com/p0deje/vagrant-exec) to execute commands remotely through Vagrant, and if you can't get Console to work with `--target`, you might want to try doing this (it's more convenient than logging into the VM just to run a Drupal VM command!).
+
+First, install the plugin:
+
+    vagrant plugin install vagrant-exec
+
+Add the following to a `Vagrantfile.local` in your project (set `directory` to your drupal docroot):
+
+```ruby
+if Vagrant.has_plugin?('vagrant-exec')
+  config.exec.commands '*', directory: '/var/www/drupal'
+end
+```
+
+Now you can execute any Drupal Console command—even interactive ones!—from the host:
+
+    vagrant exec bin/drupal generate:module

box/docs/extras/drush.md

@@ -0,0 +1,81 @@
+If you have [Drush](http://www.drush.org) and Ansible installed on your host workstation, and would like to interact with a Drupal site running inside Drupal VM, there are drush aliases automatically created by Drupal VM for each of the virtual hosts you have configured.
+
+With the example configuration, you can manage the example Drupal site using the Drush alias `@drupalvm.test`. For example, to check if Drush can connect to the site in Drupal VM, run:
+
+```
+$ drush @drupalvm.test status
+ Drupal version         :  8.0.0-dev
+ Site URI               :  drupalvm.test
+ Database driver        :  mysql
+ Database hostname      :  localhost
+ Database port          :
+ Database username      :  drupal
+ Database name          :  drupal
+ Database               :  Connected
+ Drupal bootstrap       :  Successful
+ Drupal user            :  Anonymous
+ Default theme          :  bartik
+ Administration theme   :  seven
+ PHP executable         :  /usr/bin/php
+ PHP configuration      :  /etc/php5/cli/php.ini
+ PHP OS                 :  Linux
+ Drush script           :  /usr/local/share/drush/drush.php
+ Drush version          :  7.0-dev
+ Drush temp directory   :  /tmp
+ Drush configuration    :
+ Drush alias files      :
+ Drupal root            :  /var/www/drupalvm/drupal
+ Site path              :  sites/default
+ File directory path    :  sites/default/files
+ Temporary file         :  /tmp
+ directory path
+ Active config path     :  [...]
+ Staging config path    :  [...]
+```
+
+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.test', 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
+
+_For sql-sync to work between two remotes make sure you are running Drush 8.0.3 or later on your host and your guest machine, as well as 7.1.0 or later on the remote._
+
+If you're locked to an older version of Drush, it is likely that Drush will try to run the command from the `@destination` instead of from your host computer, which means you need to move your `@remote` alias to Drupal VM as well. You can place the file in any of the [directories Drush searches](https://github.com/drush-ops/drush/blob/5a1328d6e9cb919a286e70360df159d1b4b15d3e/examples/example.aliases.drushrc.php#L43:L51), for example `/home/vagrant/.drush/<remote-alias>.aliases.drushrc.php`.
+
+If you're still having issues, you can avoid `sql-sync` entirely and pipe the mysqldump output yourself with:
+
+```
+drush @remote sql-dump | drush @drupalvm.drupalvm.test sql-cli
+```
+
+## Running `drush core-cron` as a cron job.
+
+Using the `drupalvm_cron_jobs` list in `config.yml` you can configure your VM to automatically run cron tasks eg. every 30 minutes.
+
+```yaml
+drupalvm_cron_jobs:
+  - name: "Drupal Cron"
+    minute: "*/30"
+    job: "{{ drush_path }} -r {{ drupal_core_path }} core-cron"
+```
+
+_Cron jobs are added to the vagrant user's crontab. Keys include name (required), minute, hour, day, weekday, month, job (required), and state._
+
+For a list of available role variables, see the [`geerlingguy.drush` Ansible role's README](https://github.com/geerlingguy/ansible-role-drush#readme).

box/docs/extras/elasticsearch.md

@@ -0,0 +1,24 @@
+[Elasticsearch](https://www.elastic.co/products/elasticsearch) is a search engine based on Lucene. It provides a distributed, multitenant-capable full-text search engine with an HTTP web interface and schema-free JSON documents.
+
+To enable Elasticsearch in Drupal VM just make sure `elasticsearch` is in the list of `installed_extras` in your `config.yml`, and when you build Drupal VM, the latest version of Elasticsearch will be installed.
+
+The URL to connect to the local elasticsearch server (assuming you're using the default `elasticsearch_http_port` of 9200) from Drupal is:
+
+    http://localhost:9200
+
+To access Elasticsearch from the host computer requires changing the IP address to listen on a specific interface, or 0.0.0.0 to listen on all interfaces.
+
+    elasticsearch_network_host: 0.0.0.0
+
+The Elasticsearch server can then be accessed at the configured domain:
+
+    http://drupalvm.test:9200
+
+## Elasticsearch configuration
+
+You can add configuration for Elasticsearch by setting the appropriate variables inside `config.yml` before you build Drupal VM.
+
+    elasticsearch_network_host: localhost
+    elasticsearch_http_port: 9200
+
+For a list of available role variables, see the [`geerlingguy.elasticsearch` Ansible role's README](https://github.com/geerlingguy/ansible-role-elasticsearch#readme).

box/docs/extras/java.md

@@ -0,0 +1,4 @@
+Java will automatically be installed if you enabled any of the `installed_extras` that depend on it.
+If you have any other use case for installing it, just make sure `java` is in the list of `installed_extras` in your `config.yml`.
+
+For a list of available role variables, see the [`geerlingguy.java` Ansible role's README](https://github.com/geerlingguy/ansible-role-java#readme).

box/docs/extras/mailhog.md

@@ -0,0 +1,13 @@
+By default, Drupal VM redirects all PHP emails to [MailHog](https://github.com/mailhog/MailHog) (instead of sending them to the outside world). You can access the MailHog UI at [http://drupalvm.test:8025/](http://drupalvm.test:8025) (or whatever domain you have configured in `config.yml`).
+
+## Disable MailHog
+
+If you don't want to use MailHog, you can set the following override (back to PHP's default, as defined in the [`geerlingguy.php`](https://github.com/geerlingguy/ansible-role-php#role-variables) role) in your `config.yml` file:
+
+```yaml
+php_sendmail_path: "/usr/sbin/sendmail -t -i"
+```
+
+After doing this, you can also prevent MailHog's installation by removing `mailhog` from the `installed_extras` list.
+
+For a list of available role variables, see the [`geerlingguy.mailhog` Ansible role's README](https://github.com/geerlingguy/ansible-role-mailhog#readme).

box/docs/extras/memcached.md

@@ -0,0 +1,17 @@
+[Memcached](https://memcached.org/) is an in-memory caching system, much like [Redis](redis.md). While [Varnish](varnish.md) is generally used to improve performance for anonymous users, `memcached` is used to improve the performance for logged in users.
+
+To enable Memcached in Drupal VM:
+
+1. Make sure `memcached` is in the list of `installed_extras` in your `config.yml`.
+2. Install the [Memcache API](https://www.drupal.org/project/memcache) module.
+3. Enable the module before you configure it in the next step.
+4. Add the following to your `settings.php`
+
+```php
+// Make memcache the default cache class.
+$settings['cache']['default'] = 'cache.backend.memcache';
+```
+
+There's a lot more configuration available and the best resource is generally the [Memcache API module's README](http://cgit.drupalcode.org/memcache/tree/README.txt?h=8.x-2.x).
+
+For a list of available role variables, see the [`geerlingguy.memcached` Ansible role's README](https://github.com/geerlingguy/ansible-role-memcached#readme).

box/docs/extras/newrelic.md

@@ -0,0 +1,23 @@
+The [New Relic PHP agent](https://docs.newrelic.com/docs/agents/php-agent/getting-started/new-relic-php) monitors your application to help you identify and solve performance issues.
+
+## Getting Started - Installing Prerequisites
+
+To make New Relic available globally for all your projects within Drupal VM, make the following changes inside `config.yml`, then run `vagrant up` (or `vagrant provision` if the VM is already built):
+
+```yaml
+# Make sure newrelic is not commented out in the list of installed_extras:
+installed_extras:
+  [...]
+  - newrelic
+  [...]
+
+# Set vars for your New Relic account:
+# `newrelic` must be in installed_extras for this to work.
+newrelic_license_key: yourkey
+# Customize any additional vars relevant to your project needs.
+# See all vars: https://github.com/weareinteractive/ansible-newrelic#variables
+```
+
+See [New Relic for PHP](https://docs.newrelic.com/docs/agents/php-agent/getting-started/new-relic-php) for help getting started.
+
+For a list of available role variables, see the [`franklinkim.newrelic` Ansible role's README](https://github.com/weareinteractive/ansible-newrelic#readme).

box/docs/extras/nodejs.md

@@ -0,0 +1,30 @@
+Node.js is used for many different purposes, but with Drupal, it is most often used as part of a toolset for Front End development or certain CI tasks.
+
+Drupal VM includes built-in support for Node.js—all you need to do is make sure `nodejs` is listed in the list of `installed_extras` inside `config.yml` before your provision Drupal VM.
+
+## Choosing a version of Node.js
+
+You can choose a version of Node.js to install using the `nodejs_version` variable in `config.yml`. See the [`geerlingguy.nodejs` Ansible role's README](https://github.com/geerlingguy/ansible-role-nodejs#readme) for all the currently-available versions for your OS.
+
+```yaml
+nodejs_version: "0.12"
+```
+
+## Installing global packages via NPM
+
+To install packages globally, you can add them to the list of `nodejs_npm_global_packages` in `config.yml`. As an example, many developers use `phantomjs` as a ghost web driver for Behat tests inside Drupal VM. To install it globally, add it to the list:
+
+```yaml
+nodejs_npm_global_packages:
+  - phantomjs
+```
+
+You can even specify a specific version to install:
+
+```yaml
+nodejs_npm_global_packages:
+  - name: phantomjs
+    version: 2.1.7
+```
+
+For a list of available role variables, see the [`geerlingguy.nodejs` Ansible role's README](https://github.com/geerlingguy/ansible-role-nodejs#readme).

box/docs/extras/pimpmylog.md

@@ -0,0 +1,20 @@
+[Pimp my Log](http://pimpmylog.com/) is a PHP-based web GUI for viewing log files on a given server. By default, it is installed on Drupal VM, and you can access it at the URL [http://pimpmylog.drupalvm.test/](http://pimpmylog.drupalvm.test) (as long as you have a hosts entry for that URL pointing at Drupal VM's IP address!).
+
+By default, it will find the default Apache 2 `access.log` and `error.log` files, but it will not find other logs, like MySQL or extra Apache virtualhost logs.
+
+When configuring Pimp my Log (on the first visit to [pimpmylog.drupalvm.test](http://pimpmylog.drupalvm.test)), you can add extra paths in the UI, or you can add them after the fact by manually editing the configuration file, which by default is stored at `/usr/share/php/pimpmylog/config.user.php`. You can also delete that file and re-configure Pimp my Log via the web UI.
+
+Some log files you may be interested in monitoring:
+
+  - `/var/log/apache2/access.log`
+  - `/var/log/apache2/error.log` (this log will show Apache and PHP notices/warnings/errors)
+  - `/var/log/apache2/other_vhosts_access.log`
+  - `/var/log/mysql.err` (MySQL error log)
+  - `/var/log/mysql-slow.log` (MySQL slow query log)
+  - `/var/log/syslog` (enable the Drupal syslog module to route watchdog log entries to this file)
+
+For MySQL logs, you might want to read through the PML docs on [MySQL](http://support.pimpmylog.com/kb/softwares/mysql).
+
+It might be necessary to grant read permissions to the other group (e.g. `chmod o+r /var/log/mysql.err`) on some log files in order for Pimp My Log to be able to parse them.
+
+For a list of available role variables, see the [`geerlingguy.pimpmylog` Ansible role's README](https://github.com/geerlingguy/ansible-role-pimpmylog#readme).

box/docs/extras/redis.md

@@ -0,0 +1,17 @@
+[Redis](https://redis.io/) is an in-memory caching system, much like [Memcached](memcached.md). While [Varnish](varnish.md) is generally used to improve performance for anonymous users, `redis` is used to improve the performance for logged in users.
+
+To enable Redis in Drupal VM:
+
+1. Make sure `redis` is in the list of `installed_extras` in your `config.yml`.
+2. Install the [Redis](https://www.drupal.org/project/redis) module.
+3. Enable the module before you configure it in the next step.
+4. Add the following to your `settings.php`
+
+```php
+// Make redis the default cache class.
+$settings['cache']['default'] = 'cache.backend.redis'
+```
+
+There's a lot more configuration available and the best resource is generally the [Redis module's README](http://cgit.drupalcode.org/redis/tree/README.md).
+
+For a list of available role variables, see the [`geerlingguy.redis` Ansible role's README](https://github.com/geerlingguy/ansible-role-redis#readme).

box/docs/extras/ruby.md

@@ -0,0 +1,15 @@
+Ruby is used for many different purposes, but with Drupal, it is most often used as part of a toolset for Front End development or certain CI tasks.
+
+Drupal VM includes built-in support for Ruby—all you need to do is make sure `ruby` is listed in the list of `installed_extras` inside `config.yml` before your provision Drupal VM.
+
+## Installing gems
+
+To install ruby gems, you can add them to the list of `ruby_install_gems` in `config.yml`.
+
+```yaml
+ruby_install_gems:
+  - sass
+  - compass
+```
+
+For a list of available role variables, see the [`geerlingguy.ruby` Ansible role's README](https://github.com/geerlingguy/ansible-role-ruby#readme).

box/docs/extras/selenium.md

@@ -0,0 +1,105 @@
+Behat is an open source behavior-driven development tool for PHP. You can use Behat to build and run automated tests for site functionality on your Drupal sites, and Drupal VM has excellent built-in support for Behat, using Selenium to run tests in a headless instance of either Google Chrome (default) or Firefox.
+
+## Getting Started - Installing Prerequisites
+
+To make Behat available globally for all your projects within Drupal VM, make the following changes inside `config.yml`, then run `vagrant up` (or `vagrant provision` if the VM is already built):
+
+```yaml
+# Make sure selenium is not commented out in the list of installed_extras:
+installed_extras:
+  [...]
+  - selenium
+  [...]
+
+# Add the following package to composer_global_packages or your Drupal project:
+composer_global_packages:
+  - { name: drupal/drupal-extension, release: '*' }
+```
+
+After Drupal VM is finished provisioning, you should be able to log in and run the following command to make sure Behat is installed correctly:
+
+```
+$ behat --version
+behat version 3.0.15
+```
+
+_You can also include `drupal/drupal-extension` directly in your project's `composer.json` file, and install the dependencies per-project._
+
+## Setting up Behat for your project
+
+Using the default Drupal site as an example (it's installed in `/var/www/drupalvm/drupal` by default, and is shared to the `./drupal` folder inside the drupal-vm directory on your host machine), the following steps will help you get your first Behat tests up and running!
+
+  1. Create a `behat.yml` file inside the docroot of your site (e.g. create this file alongside the rest of the Drupal codebase at `/var/www/drupalvm/drupal/behat.yml`), with the following contents:
+
+        default:
+          suites:
+            web_features:
+              paths: [ %paths.base%/features/web ]
+              contexts:
+                - WebContext
+                - Drupal\DrupalExtension\Context\DrupalContext
+                - Drupal\DrupalExtension\Context\MinkContext
+                - Drupal\DrupalExtension\Context\MessageContext
+                - Drupal\DrupalExtension\Context\DrushContext
+          extensions:
+            Behat\MinkExtension:
+              goutte: ~
+              javascript_session: selenium2
+              selenium2:
+                wd_host: http://drupalvm.test:4444/wd/hub
+              base_url: http://drupalvm.test
+            Drupal\DrupalExtension:
+              blackbox: ~
+              api_driver: 'drupal'
+              drupal:
+                drupal_root: '/var/www/drupalvm/drupal/web'
+              region_map:
+                content: "#content"
+
+  2. Log into Drupal VM with `vagrant ssh`, change directory to the Drupal site root (`cd /var/www/drupalvm/drupal`), then run `behat --init` to initialize the `features` folder where you will place test cases.
+  3. From either inside the VM or on the host machine, open up the new `features/web` folder Behat just created. Inside _that_ folder, create `HomeContent.feature` with the following contents:
+
+        Feature: Test DrupalContext
+          In order to prove Behat is working correctly in Drupal VM
+          As a developer
+          I need to run a simple interface test
+
+          Scenario: Viewing content in a region
+            Given I am on the homepage
+            Then I should see "No front page content has been created yet" in the "content"
+
+  4. Now, inside Drupal VM, change directory to `/var/www/drupalvm/drupal` again, and run the command `behat` (which runs all the tests you've created—which should just be one so far).
+
+If everything was done correctly, you should see:
+
+```console
+$ behat
+Feature: Test DrupalContext
+  In order to prove Behat is working correctly in Drupal VM
+  As a developer
+  I need to run a simple interface test
+
+  Scenario: Viewing content in a region                                             # features/drupal/HomeContent.feature:6
+    Given I am on the homepage                                                      # Drupal\DrupalExtension\Context\MinkContext::iAmOnHomepage()
+    Then I should see "No front page content has been created yet" in the "content" # Drupal\DrupalExtension\Context\MinkContext::assertRegionText()
+
+1 scenario (1 passed)
+2 steps (2 passed)
+0m0.56s (26.48Mb)
+```
+
+Hooray! Now you're ready to get started testing ALL THE THINGS! Check out the following resources for more information about Behat and Drupal:
+
+  - [Behat 3.0 Documentation](http://behat.readthedocs.org/en/v3.0/)
+  - [Drupal Extension Documentation](https://behat-drupal-extension.readthedocs.org/en/3.0/)
+
+## Debugging issues
+
+There are many different ways you can run Behat tests via PhantomJS and other drivers, and some people have encountered issues and workarounds with different approaches. Here are some relevant issues you can read through for more background:
+
+  - [Selenium Questions](https://github.com/geerlingguy/drupal-vm/issues/367)
+  - [Trying to achieve a Visual Regression Testing Strategy](https://github.com/geerlingguy/drupal-vm/issues/421)
+
+Also, see Acquia's [BLT](https://github.com/acquia/blt) project for a good example of Behat test integration with Drupal VM.
+
+For a list of available role variables, see the [`arknoll.selenium` Ansible role's README](https://github.com/arknoll/ansible-role-selenium#readme).

box/docs/extras/solr.md

@@ -0,0 +1,32 @@
+Drupal VM makes using Apache Solr easy; just make sure `solr` is in the list of `installed_extras` in your `config.yml`, and when you build Drupal VM, the latest version of Apache Solr will be installed.
+
+Inside of Drupal, you can use any of the available Apache Solr integration modules (e.g. [Apache Solr Search](https://www.drupal.org/project/apachesolr) or [Search API Solr Search](https://www.drupal.org/project/search_api_solr)), and when you configure the modules, follow the installation instructions included with the module.
+
+The URL to connect to the local solr server (assuming you're using the default `solr_port` of 8983) from Drupal is:
+
+    http://localhost:8983/solr/collection1
+
+This will connect to the default search core (`collection1`) set up by Solr. If you are using a multisite installation and want to have a search core per Drupal site, you can add more cores through Apache Solr's admin interface (visit `http://drupalvm.test:8983/solr/`), then connect to each core by adding the core name to the end of the above URL (e.g. `core2` would be `http://localhost:8983/solr/core2`).
+
+## Using Different Solr versions
+
+Drupal VM installs Apache Solr 5.x by default, but you can use 6.x, 4.x, or other versions instead. To do this, [see the version-specific test examples](https://github.com/geerlingguy/ansible-role-solr/tree/master/tests) in the `geerlingguy.solr` role.
+
+One important note: If you use Solr 5.x or 6.x (or later), you need to make sure your VM has Java 8+. By default, many of the supported OSes only install Java 7. To install Java 8, see the `geerlingguy.java` role examples for [installing Java 8 on RHEL/CentOS or Ubuntu < 16.04](https://github.com/geerlingguy/ansible-role-java#example-playbook-install-openjdk-8).
+
+## Configuring the Solr search core for Drupal
+
+Before Drupal content can be indexed correctly into Apache Solr, you will need to copy the Drupal Apache Solr Search or Search API Apache Solr configuration into place, and restart Apache Solr. Drupal VM comes with an example post provision script for automating this. Simply add it to `post_provision_scripts`:
+
+```yaml
+post_provision_scripts:
+ - "../examples/scripts/configure-solr.sh"
+```
+
+Note that for Drupal 8, this script will create a new search core named `d8` (rather than modifying the default core `collection1`).
+
+## Extra Solr configuration
+
+You can add extra configuration for Solr, like the minimum and maximum memory allocation for the JVM (`solr_xms` and `solr_xmx`), and even the `solr_version`, by setting the appropriate variables inside `config.yml` before you build Drupal VM.
+
+For a list of available role variables, see the [`geerlingguy.solr` Ansible role's README](https://github.com/geerlingguy/ansible-role-solr#readme).

box/docs/extras/tideways.md

@@ -0,0 +1,17 @@
+The Tideways PHP Extension is a well-maintained fork of the XHProf code and works with either the [XHProf](https://www.drupal.org/project/xhprof) or [Tideways](https://www.drupal.org/project/tideways) module to profile page views.
+
+To use Tideways make sure `tideways` is in the list of `installed_extras`.
+
+**Note**: You should only enable one code profiler at a time—e.g. when using [Blackfire](blackfire.md), disable [XHProf](xhprof.md), [Tideways](tideways.md) and [XDebug](xdebug.md).
+
+### Profiling with the XHProf Module
+
+To enable profiling of Drupal pages using the Tideways PHP Extension, follow the directions for [configuring the XHProf and the XHProf module](xhprof.md#xhprof-module), but choose the _Tideways_ extension under the _Profiling settings_ section.
+
+As with the XHProf extension, you can view callgraphs (and a listing of all stored runs) using Drupal VM's own XHProf UI installation by visiting [http://xhprof.drupalvm.test/](http://xhprof.drupalvm.test) and clicking on the relevant run, then clicking the _[View Full Callgraph]_ link.
+
+### Profiling with the Tideways module
+
+Instructions for profiling with the Tideways module through the [tideways.io](https://tideways.io) service will be added after the following issue is resolved: [Can't install latest dev release on 8.x](https://www.drupal.org/node/2843481).
+
+For a list of available role variables, see the [`geerlingguy.php-tideways` Ansible role's README](https://github.com/geerlingguy/ansible-role-php-tideways#readme).

box/docs/extras/upload-progress.md

@@ -0,0 +1,3 @@
+To enable the Upload progress PHP extension make sure `upload-progress` is listed in the list of `installed_extras` inside `config.yml` before your provision Drupal VM.
+
+For a list of available role variables, see the [`thom8.php-upload-progress` Ansible role's README](https://github.com/thom8/ansible-role-php-upload-progress#readme).

box/docs/extras/varnish.md

@@ -0,0 +1,64 @@
+[Varnish](https://www.varnish-software.com/) is an advanced reverse proxy and HTTP accelerator. At a basic level, it can act as a lightweight, very fast, and highly configurable static cache in front of your Drupal site. It also works as a load balancer and has some other tricks up it's sleeve, but for Drupal VM's purposes, you can think of it as a simple way to supercharge your site via proxy caching.
+
+To enable Varnish, make sure `varnish` is in the list of your `installed_extras` in `config.yml`, and run `vagrant provision`.
+
+There are a few varnish configuration variables further down in `default.config.yml` that you may wish to configure. You can use your own `.vcl` file template (instead of the generic Drupal 7-focused generic one) by editing the `varnish_default_vcl_template_path`, and you can use a different port for Varnish by changing `varnish_listen_port`.
+
+If you'd like to use Varnish on port 80, and switch Apache to a different backend port, you can do so pretty easily; just make sure you have the following values set in your `config.yml` file, and run `vagrant provision` to have Ansible make the necessary changes:
+
+```yaml
+apache_listen_port: "81"
+
+varnish_listen_port: "80"
+varnish_default_backend_port: "81"
+```
+
+## Required Drupal Changes
+
+In order for Varnish to actually do anything helpful (instead of just pass through requests and responses to/from the Apache backend), you need to set a few settings in Drupal:
+
+
+  - On the `/admin/config/development/performance` page:
+    - Check the 'Cache pages for anonymous users' setting (if it's not already enabled).
+    - Set both the 'Minimum Cache Lifetime' and 'Expiration of cached pages' values to something reasonable (e.g. 5, 10, or 15 minutes—or much more if you don't update the content on the site much!).
+
+You will also need to make a few small changes to your site's `settings.php` configuration to make Drupal work correctly behind a reverse proxy like Varnish:
+
+```php
+$settings['reverse_proxy'] = TRUE;
+$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).

box/docs/extras/xdebug.md

@@ -0,0 +1,78 @@
+[XDebug](https://xdebug.org/) is a useful tool for debugging PHP applications, but it uses extra memory and CPU for every request, so is disabled by default.
+
+To enable XDebug, do the following in `config.yml`:
+
+  - Change `php_xdebug_default_enable` (and, optionally, `php_xdebug_coverage_enable` to get code coverage reports) to `1`
+  - Make sure `xdebug` is in the list of `installed_extras`
+
+If you don't need to use XDebug, you can comment it out or remove it from `installed_extras` before you `vagrant up` Drupal VM.
+
+### PHPStorm and XDebug with Drupal VM
+
+To use XDebug with PHPStorm, change the `php_xdebug_idekey` variable as shown below in `config.yml`, and then run `vagrant provision` to reconfigure the VM:
+
+```yaml
+php_xdebug_idekey: PHPSTORM
+```
+
+### Sublime Text and XDebug with Drupal VM
+
+To use XDebug with Sublime Text, change the `php_xdebug_idekey` variable as shown below in `config.yml`, and then run `vagrant provision` to reconfigure the VM:
+
+```yaml
+php_xdebug_idekey: sublime.xdebug
+```
+
+To configure a Sublime Text project to use XDebug when debugging, add the following `settings` key to your project's `.sublime-project` file:
+
+```json
+ "settings": {
+   "xdebug": {
+     "path_mapping": {
+       "/var/www/projectname/docroot" : "/Users/geerlingguy/Sites/projectname/docroot",
+     },
+     "url": "http://local.projectname.com/",
+     "super_globals": true,
+     "close_on_stop": true
+   }
+ }
+```
+
+This assumes you have already installed [SublimeTextXdebug](https://github.com/martomo/SublimeTextXdebug) via Package Control.
+
+### NetBeans and XDebug with Drupal VM
+
+To use XDebug with NetBeans, change the `php_xdebug_idekey` variable as shown below in `config.yml`, and then run `vagrant provision` to reconfigure the VM.
+
+```yaml
+php_xdebug_idekey: netbeans-xdebug
+```
+
+### XDebug over SSH/Drush
+
+As long as `xdebug` is listed in `installed_extras` Drupal VM is configured to accept the `PHP_IDE_CONFIG`, `XDEBUG_CONFIG` and `PHP_OPTIONS` environment variables over SSH and this can be used to set up some IDE's as well as enable XDebug on a per request basis:
+
+```
+PHP_OPTIONS="-d xdebug.default_enable=1" drush @drupalvm.drupalvm.test migrate-import
+```
+
+To send the environment variables when using `vagrant ssh`, [create a `Vagrantfile.local`](../extending/vagrantfile.md) with:
+
+```
+config.ssh.forward_env = ['PHP_IDE_CONFIG', 'XDEBUG_CONFIG', 'PHP_OPTIONS']
+```
+
+And you can run:
+
+```
+XDEBUG_CONFIG="-d default_enable=1" vagrant ssh -c 'php /var/www/drupalvm/drupal/web/core/scripts/run-tests.sh --url http://drupalvm.test --all'
+XDEBUG_CONFIG="-d default_enable=1" vagrant ssh -c 'cd /var/www/drupalvm/drupal/web/core; php ../../vendor/bin/phpunit tests/Drupal/Tests/Core/Password/PasswordHashingTest.php'
+```
+
+## Profiling code with XDebug
+
+While most people use XDebug only for debugging purposes, you can also use it for profiling. It's not as commonly used for profiling as either Blackfire or XHProf, but it works!
+
+**Note**: You should only enable one code profiler at a time—e.g. when using [Blackfire](blackfire.md), disable [XHProf](xhprof.md), [Tideways](tideways.md) and [XDebug](xdebug.md).
+
+For a list of available role variables, see the [`geerlingguy.php-xdebug` Ansible role's README](https://github.com/geerlingguy/ansible-role-php-xdebug#readme).

box/docs/extras/xhprof.md

@@ -0,0 +1,20 @@
+[XHProf](http://xhprof.io/) allows easy code profiling and can be used in many different ways. Ensure `xhprof` is in the list of `installed_extras` inside `config.yml`.
+
+_Note: XHProf does currently not work with PHP 7.1+. The PHP extension has barely been maintained since Facebook abandoned the project around 2015, so it's difficult to get it running under newer versions of PHP. If you require support for PHP 7.1 or newer, you should use [Tideways](tideways.md) instead._
+
+### XHProf module
+
+The easiest way to use XHProf to profile your PHP code on a Drupal site is to install the [XHProf](https://www.drupal.org/project/xhprof) module, then in XHProf's configuration (at `/admin/config/development/xhprof`), check the 'Enable profiling of page views and drush requests' checkbox.
+
+The XHProf module doesn't include built-in support for callgraphs, but there's an issue to [add callgraph support](https://www.drupal.org/node/1470740).
+
+You can view callgraphs (and a listing of all stored runs) using Drupal VM's own XHProf installation by visiting [http://xhprof.drupalvm.test/](http://xhprof.drupalvm.test) and clicking on the relevant run, then clicking the _[View Full Callgraph]_ link.
+
+### Devel module (deprecated)
+
+The Devel module also *used* to provide XHProf configuration, and setting the options below would allow Devel's XHProf integration to work correctly with Drupal VM's XHProf installation:
+
+  - **xhprof directory**: `/usr/share/php`
+  - **XHProf URL**: `http://xhprof.drupalvm.test`
+
+**Note**: You should only enable one code profiler at a time—e.g. when using [Blackfire](blackfire.md), disable [XHProf](xhprof.md), [Tideways](tideways.md) and [XDebug](xdebug.md).