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
+```