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

box/docs/deployment/composer-dependency.md

@@ -0,0 +1,141 @@
+To make future Drupal VM updates easier to integrate with an existing project, you might consider the more complex setup of installing Drupal VM as a `composer` dependency. Using a delegating `Vagrantfile` you are able to run `vagrant` commands anywhere in your project as well as separate your custom configuration files from Drupal VM's own files.
+
+### Add Drupal VM as a Composer dependency
+
+Add Drupal VM as a development dependency to your `composer.json`.
+
+```
+composer require --dev geerlingguy/drupal-vm
+```
+
+### Setup your configuration files
+
+Add and configure the `config.yml` anywhere you like, in this example we place it in a `config/` directory.
+
+_Note: This will be the directory where Drupal VM looks for other local configuration files as well. Such as `drupal_build_makefile` and `local.config.yml`._
+
+```
+├── composer.json
+├── config/
+│   ├── config.yml
+│   ├── local.config.yml
+│   └── Vagrantfile.local
+├── docroot/
+│   ├── ...
+│   └── index.php
+└── vendor/
+    ├── ...
+    └── geerlingguy/
+        └── drupal-vm/
+```
+
+Change the [build strategy to use your `composer.json`](composer.md#using-composer-when-drupal-vm-is-a-composer-dependency-itself) file by setting:
+
+```yaml
+drupal_build_composer_project: false
+drupal_build_composer: true
+drupal_composer_path: false
+drupal_composer_install_dir: "/var/www/drupalvm"
+drupal_core_path: "{{ drupal_composer_install_dir }}/docroot"
+```
+
+If you intened to use the devel module, it must be added as a requirement to your `composer.json` file. Alternatively, if you do not intend to use it remove it from `drupal_enabled_modules` in your `config.yml` file:
+
+```yaml
+drupal_enabled_modules: []
+```
+
+### Create a delegating `Vagrantfile`
+
+Create a delegating `Vagrantfile` that will catch all your `vagrant` commands and send them to Drupal VM's own `Vagrantfile`. Place this file in your project's root directory.
+
+```ruby
+# The absolute path to the root directory of the project. Both Drupal VM and
+# the config file need to be contained within this path.
+ENV['DRUPALVM_PROJECT_ROOT'] = "#{__dir__}"
+# The relative path from the project root to the config directory where you
+# placed your config.yml file.
+ENV['DRUPALVM_CONFIG_DIR'] = "config"
+# The relative path from the project root to the directory where Drupal VM is located.
+ENV['DRUPALVM_DIR'] = "vendor/geerlingguy/drupal-vm"
+
+# Load the real Vagrantfile
+load "#{__dir__}/#{ENV['DRUPALVM_DIR']}/Vagrantfile"
+```
+
+When you issue `vagrant` commands anywhere in your project tree this file will be detected and used as a delegator for Drupal VM's own Vagrantfile.
+
+Your project structure should now look like this:
+
+```
+├── Vagrantfile
+├── composer.json
+├── config/
+│   ├── config.yml
+│   ├── local.config.yml
+│   └── Vagrantfile.local
+├── docroot/
+│   ├── ...
+│   └── index.php
+└── vendor/
+    ├── ...
+    └── geerlingguy/
+        └── drupal-vm/
+```
+
+### Provision the VM
+
+Finally provision the VM using the delegating `Vagrantfile`.
+
+```sh
+vagrant up
+```
+
+_Important: you should never issue `vagrant` commands through Drupal VM's own `Vagrantfile` from now on. If you do, it will create a secondary VM in that directory._
+
+## Drupal VM in a subdirectory without composer
+
+If you're not using `composer` in your project you can still download  Drupal VM (or add it as a git submodule) to any subdirectory in your project. As an example let's name that directory `box/`.
+
+```
+├── docroot/
+│   ├── ...
+│   └── index.php
+└── box/
+    ├── ...
+    ├── default.config.yml
+    └── Vagrantfile
+```
+
+Configure your `config.yml` as mentioned in the [`composer` section](#setup-your-configuration-files) above.
+
+```yaml
+post_provision_scripts:
+  # The default provided in `default.config.yml`:
+  - "../../examples/scripts/configure-solr.sh"
+  # With Drupal VM in a toplevel subdirectory
+  - "{{ config_dir }}/../examples/scripts/configure-solr.sh"
+```
+
+Your directory structure should now look like this:
+
+```
+├── Vagrantfile
+├── config/
+│   ├── config.yml
+│   ├── local.config.yml
+│   └── Vagrantfile.local
+├── docroot/
+│   ├── ...
+│   └── index.php
+└── box/
+    ├── ...
+    ├── default.config.yml
+    └── Vagrantfile
+```
+
+Provision the VM using the delegating `Vagrantfile`.
+
+```sh
+vagrant up
+```

box/docs/deployment/composer-package.md

@@ -0,0 +1,18 @@
+Out of the box Drupal VM is configured to use `composer create-project` to build a Drupal 8 codebase.
+
+This is set up with the following variables in `config.yml`:
+
+  - Composer will build the project if `drupal_build_composer_project` is `true`, and `drupal_build_makefile` and `drupal_build_composer` are both `false`.
+  - The Composer package is defined by `drupal_composer_project_package`.
+  - Adjust the create-project CLI options in `drupal_composer_project_options` as well as add additional dependencies in `drupal_composer_dependencies`.
+  - Ensure that the webroot configured in the Composer package matches the one set in `drupal_core_path`. The default is set to `web/`.
+
+With [acquia/lightning-project](https://github.com/acquia/lightning-project) as an example your `config.yml` settings would be:
+
+```yaml
+drupal_composer_project_package: "acquia/lightning-project:^8.1.0"
+drupal_composer_project_options: "--prefer-dist --stability rc --no-interaction"
+drupal_core_path: "{{ drupal_composer_install_dir }}/docroot"
+```
+
+_Opting for composer based installs will most likely increase your VM's time to provision considerably. Find out how you can [improve composer build performance](../other/performance.md#improving-composer-build-performance)._

box/docs/deployment/composer.md

@@ -0,0 +1,28 @@
+Drupal VM is configured to use `composer create-project` to build a Drupal 8 codebase by default but supports building Drupal from a custom `composer.json` file as well.
+
+1. Copy `example.drupal.composer.json` to `drupal.composer.json` and modify it to your liking.
+2. Use the Composer build system by setting `drupal_build_composer: true` in your `config.yml` (make sure `drupal_build_makefile` and `drupal_build_composer_project` are set to `false`).
+3. Ensure `drupal_core_path` points to the webroot directory: `drupal_core_path: {{ drupal_composer_install_dir }}/web`
+
+```yaml
+drupal_build_makefile: false
+drupal_build_composer_project: false
+drupal_build_composer: true
+drupal_core_path: "{{ drupal_composer_install_dir }}/web"
+```
+
+_The file set in `drupal_composer_path` (which defaults to `drupal.composer.json`) will be copied from your host computer into the VM's `drupal_composer_install_dir` and renamed `composer.json`._
+
+## Using Composer when [Drupal VM is a composer dependency itself](composer-dependency.md)
+
+In the scenario where you have an existing `composer.json` in the root of your project, follow the usual steps for installing with a composer.json but instead of creating a `drupal.composer.json` file, disable the transfering of the file by setting `drupal_composer_path: false`, and change `drupal_composer_install_dir` to point to the the directory where it will be located. If `drupal_composer_path` is not truthy, Drupal VM assumes it already exists.
+
+```yaml
+drupal_build_composer_project: false
+drupal_build_composer: true
+drupal_composer_path: false
+drupal_composer_install_dir: "/var/www/drupalvm"
+drupal_core_path: "{{ drupal_composer_install_dir }}/docroot"
+```
+
+_Opting for composer based installs will most likely increase your VM's time to provision considerably. Find out how you can [improve composer build performance](../other/performance.md#improving-composer-build-performance)._

box/docs/deployment/drush-make.md

@@ -0,0 +1,16 @@
+If you want to build a Drupal site using a [Drush make file](http://www.drush.org/en/master/make/) instead of composer, set `drupal_build_composer_project: false`, `drupal_build_makefile: true` and either use the `example.drupal.make.yml` file as a base, or use your own Drush make file: just place it or symlink it into the root of the Drupal VM folder with the filename `drupal.make.yml`. You can also set a separate path to the makefile using the `drush_makefile_path` variable.
+
+```yaml
+drupal_build_composer_project: false
+drupal_build_makefile: true
+```
+
+Have a look at the defaults in `default.config.yml` and tweak the settings as you'd like in your `config.yml`, then run `vagrant up` as in the Quick Start Guide. Within a few minutes, you should have your site running and available at the `drupal_domain` configured in `config.yml`, falling back to the default `http://drupalvm.test` set in `default.config.yml`.
+
+With the default settings the Drupal site will be built on the VM inside `/var/www/drupalvm/drupal/web` but the `web/` subdirectory is only required for `composer` based projects and you can simplify this directory structure by setting `drupal_core_path` to `/var/www/drupalvm/drupal`.
+
+```yaml
+drupal_build_composer_project: false
+drupal_build_makefile: true
+drupal_core_path: "/var/www/drupalvm/drupal"
+```

box/docs/deployment/git.md

@@ -0,0 +1,25 @@
+You can deploy a codebase directly inside Drupal VM via Git. You can deploy a Git-based Drupal site directly into a shared folder, or you can even deploy inside Drupal VM's own filesystem. The latter option offers better performance than any of the other deployment methods, since Drupal VM can use native filesystem caches and disk access.
+
+This is also the recommended method for deploying Drupal sites to Drupal VM when used [in production](../other/production.md)
+
+## Deploying Drupal via Git
+
+Drupal VM uses the [`geerlingguy.drupal`](https://github.com/geerlingguy/ansible-role-drupal) Ansible role to deploy and manage Drupal codebases.
+
+To deploy your Drupal project inside Drupal VM during provisioning, you need to set the following variables inside `config.yml`:
+
+    drupal_deploy: true
+    drupal_deploy_repo: "git@github.com:username/example.git"
+    drupal_deploy_dir: /var/www/drupal
+
+The above settings assume you want to deploy a Drupal codebase in the GitHub repository `username/example.git` (or any other valid Git URL to which you have access). And it will place that codebase inside `/var/www/drupal`, which you might have mounted as a shared folder, or if you want even better performance, you could configure a 'reverse mount' or just work on the codebase inside the VM.
+
+If you want to disable Drupal VM's default synced folder, set the following variable in `config.yml`:
+
+    vagrant_synced_folders: []
+
+When you run `vagrant provision` or deploy Drupal VM to a production server, the `geerlingguy.drupal` role will check out the Git repository into the `drupal_deploy_dir`.
+
+> Note: For private repositories, you can use your own SSH key if you use `ssh-agent`. On Mac or Linux, you can run `ssh-add -K` to add your default private key to the SSH Agent, or on Windows you can either use [Pageant](https://winscp.net/eng/docs/ui_pageant), an SSH agent built into your CLI emulator, or if you're on Windows 10, the SSH Agent that's installed with Ubuntu Bash.
+
+For more information about this technique, please read Jeff Geerling's blog post, [Drupal VM on Windows - a fast container for BLT project development](https://www.jeffgeerling.com/blog/2017/drupal-vm-on-windows-fast-container-blt-project-development). Note that this technique is great for better performance on Windows, but it can be used on any platform where Drupal VM is used.

box/docs/deployment/local-codebase.md

@@ -0,0 +1,61 @@
+If you already have a Drupal codebase on your host machine (e.g. in `~/Sites/my-drupal-site`), and don't want or need to build your Drupal site with a Drush make file, make the following changes to `config.yml` before building Drupal VM:
+
+## Sync your Drupal codebase to the VM
+
+Update the `vagrant_synced_folders` configuration to sync your local Drupal codebase to a folder within the machine:
+
+```yaml
+vagrant_synced_folders:
+  - local_path: ~/Sites/my-drupal-site
+    destination: /var/www/my-drupal-site
+    type: nfs
+```
+
+_If you have Drupal VM installed within your codebase, you can also set the `local_path` to a location relative to the `Vagrantfile`. This is the default setup in `default.config.yml`._
+
+## Disable the Composer project build and site install
+
+Set all the `drupal_build_*` variables and `install_site` to `false`:
+
+```yaml
+drupal_build_makefile: false
+drupal_build_composer: false
+drupal_build_composer_project: false
+...
+drupal_install_site: false
+```
+
+If you aren't copying back a database, and want to have Drupal VM run `drush si` for your Drupal site, you can leave `drupal_install_site` set to `true` and it will run a site install on your Drupal codebase using the `drupal_*` config variables.
+
+## Update `drupal_core_path`
+
+Set `drupal_core_path` to the same value as the `destination` of the synced folder you configured earlier:
+
+```yaml
+drupal_core_path: "/var/www/my-drupal-site"
+```
+
+This variable will be used for the document root of the webserver.
+
+## Set the domain
+
+By default the domain of your site will be `drupalvm.test` but you can change it by setting `drupal_domain` to the domain of your choice:
+
+```yaml
+drupal_domain: "local.my-drupal-site.com"
+```
+
+If you prefer using your domain as the root of all extra packages installed, ie. `adminer`, `xhprof` and `pimpmylog`, set it as the value of `vagrant_hostname` instead.
+
+```yaml
+vagrant_hostname: "my-drupal-site.com"
+drupal_domain: "{{ vagrant_hostname }}"
+```
+
+## Update MySQL info
+
+If you have your Drupal site configured to use a special database and/or user/password for local development (e.g. through a `settings.local.php` file), you can update the values for `mysql_databases` and `mysql_users` as well.
+
+## Build the VM, import your database
+
+Run `vagrant up` to build the VM with your codebase synced into the proper location. Once the VM is created, you can [connect to the MySQL database](../configurations/databases-mysql.md) and import your site's database to the Drupal VM, or use a [command like `drush sql-sync`](../extras/drush.md#using-sql-sync) to copy a database from another server.

box/docs/deployment/multisite.md

@@ -0,0 +1,44 @@
+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"
+
+...
+
+apache_vhosts:
+  # Drupal VM's default domain, evaluating to whatever `vagrant_hostname` is set to (drupalvm.test by default).
+  - servername: "{{ drupal_domain }}"
+    serveralias: "www.{{ drupal_domain }}"
+    documentroot: "{{ drupal_core_path }}"
+    extra_parameters: "{{ apache_vhost_php_fpm_parameters }}"
+
+  - servername: "local.second-drupal-site.com"
+    documentroot: "{{ drupal_core_path }}"
+    extra_parameters: "{{ apache_vhost_php_fpm_parameters }}"
+
+  - servername: "local.third-drupal-site.com"
+    documentroot: "{{ drupal_core_path }}"
+    extra_parameters: "{{ apache_vhost_php_fpm_parameters }}"
+```
+
+If you need additional databases and database users, add them to the list of `mysql_databases` and `mysql_users`:
+
+```yaml
+mysql_databases:
+  - name: drupal
+    encoding: utf8
+    collation: utf8_general_ci
+  - name: drupal_two
+    encoding: utf8
+    collation: utf8_general_ci
+
+mysql_users:
+  - name: drupal
+    host: "%"
+    password: drupal
+    priv: "drupal.*:ALL"
+  - name: drupal-two
+    host: "%"
+    password: drupal-two
+    priv: "drupal_two.*:ALL"
+```