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

box/docs/extending/ansible-args.md

@@ -0,0 +1,38 @@
+## Run a specific set of tagged tasks
+
+You can filter which part of the provisioning process to run by specifying a set of tags using the `DRUPALVM_ANSIBLE_TAGS` environment variable.
+
+```sh
+# E.g. xdebug, drupal, webserver, database, cron...
+DRUPALVM_ANSIBLE_TAGS=xdebug vagrant provision
+
+# Or combine them (e.g. if adding new databases and virtualhosts).
+DRUPALVM_ANSIBLE_TAGS=webserver,database vagrant provision
+```
+
+## Passing arguments to ansible during a provision
+
+You can specify an additional argument to the `ansible-playbook` command by using the `DRUPALVM_ANSIBLE_ARGS` environment variable. This can be useful when debugging a task failure.
+
+> Note the following caveats:
+>
+>   - Passing more than one argument may require special formatting. Read the [Ansible provisioner's `raw_arguments` docs](https://www.vagrantup.com/docs/provisioning/ansible_common.html#raw_arguments) for more info.
+>   - You should not quote a flag's value as you would normally do in the shell.
+
+Display verbose ansible output:
+
+```sh
+DRUPALVM_ANSIBLE_ARGS='--verbose' vagrant provision
+```
+
+Begin the provisioning at a particular task:
+
+```sh
+DRUPALVM_ANSIBLE_ARGS="--start-at-task '*post-provision shell*'" vagrant provision
+```
+
+Override a config variable:
+
+```sh
+DRUPALVM_ANSIBLE_ARGS='--extra-vars "drupal_db_backend=pgsql"' vagrant provision
+```

box/docs/extending/scripts.md

@@ -0,0 +1,48 @@
+Drupal VM allows you to run extra shell scripts and ansible task files in the beginning and at the end of the provisioning process, in case you need to do extra setup, further configure the VM, or install extra software outside the purview of Drupal VM.
+
+## Shell scripts
+
+To use an extra script, configure the path to the script (relative to `provisioning/playbook.yml`) in `config.yml`:
+
+```yaml
+pre_provision_scripts:
+  - "../scripts/pre-provision.sh"
+post_provision_scripts:
+  - "../scripts/post-provision.sh"
+```
+
+The above example results in a `pre-provision.sh` script running before the provisioning starts and a `post-provision.sh` script running after the main Drupal VM setup is complete. Pre and post provision scripts run after the first `vagrant up`, and then any time you run Vagrant provisioning (e.g. `vagrant provision` or `vagrant up --provision`).
+
+_Note: The pre provision scripts run before any other packages are installed. If you want to use commands such as `git`, you need to install the packages yourself._
+
+You can define as many scripts as you would like, and any arguments after the path will be passed to the shell script itself (e.g. `"- "../scripts/setup-paths.sh --option"`).
+
+Place your pre and post provision scripts inside a `scripts` directory in the root of your Drupal VM project directory; this directory is gitignored, so you can continue to update Drupal VM without overwriting your scripts.
+
+## Ansible task files
+
+To use an extra ansible task file, configure the path to the file (relative to `provisioning/playbook.yml`) in `config.yml`:
+
+```yaml
+pre_provision_tasks_dir: "../scripts/pre/*"
+post_provision_tasks_dir: "../scripts/post-provision.yml"
+```
+
+The path will be evaluated as a [glob pattern](https://docs.python.org/2/library/glob.html) so you can point to a single file or a directory matching a set of files.
+
+The files matched will run in alphabetical order, and as with shell scripts, pre-provision task files will run before any other packages are installed.
+
+## Ansible playbooks
+
+Out of the box Drupal VM does not support running additional playbooks or adding your own roles but using [`Vagrantfile.local` you can add any number of additional provisioners to vagrant](vagrantfile.md).
+
+As an example you might have a `local.playbook.yml` with it's own dependencies defined in `local.requirements.yml`. Place both of these next to your `config.yml` and add the following `Vagrantfile.local`.
+
+```rb
+config.vm.provision 'ansible' do |ansible|
+  ansible.playbook = "#{host_config_dir}/local.playbook.yml"
+  ansible.galaxy_role_file = "#{host_config_dir}/local.requirements.yml"
+end
+```
+
+When you run `vagrant provision` this playbook will run after Drupal VM's own playbook.

box/docs/extending/vagrantfile.md

@@ -0,0 +1,86 @@
+Out of the box Drupal VM supports having VirtualBox, Parallels as well as VMware as a provider. Besides these there are multitude of others available (for example `vagrant-aws`, `vagrant-digitalocean`).  If you want to use an unsupported provider, or otherwise modify the vagrant configuration in a way that is not exposed by Drupal VM, you can create a `Vagrantfile.local` next to your `config.yml`.
+
+The file will be sourced at the end of the `Vagrant.configure` block so you will have access to Vagrant's `config.vm` object as well as the contents of the `config.yml` file within the `vconfig` hash.
+
+To add a configuration just create a `Vagrantfile.local` in the root like so:
+
+```ruby
+config.vm.provider :virtualbox do |v|
+  # Enable GUI mode instead of running a headless machine.
+  v.gui = true
+
+  # Cap the host CPU execution at 50% usage.
+  v.customize ["modifyvm", :id, "--cpuexecutioncap", "50"]
+end
+```
+
+### Automatically install Vagrant plugins
+
+Drupal VM can be configured to ensure Vagrant plugins are installed by adding them to the `vagrant_plugins` list in your `config.yml` file.
+
+```yaml
+vagrant_plugins:
+ - name: vagrant-vbguest
+ - name: vagrant-hostsupdater
+ - name: vagrant-aws
+```
+
+### Example: Using the `vagrant-aws` provider
+
+Add the following variables to your `config.yml`.
+
+```yaml
+aws_keypair_name: 'keypair'
+aws_ami: 'ami-7747d01e'
+aws_tags_name: 'Drupal VM'
+aws_ssh_username: 'ubuntu'
+aws_ssh_private_key: '~/.ssh/aws.pem'
+```
+
+Create a `Vagrantfile.local` in the root directory of your project.
+
+```ruby
+config.vm.provider :aws do |aws, override|
+  override.nfs.functional = false
+
+  aws.access_key_id = ENV['AWS_ACCESS_KEY_ID']
+  aws.secret_access_key = ENV['AWS_SECRET_ACCESS_KEY']
+  aws.keypair_name = vconfig['aws_keypair_name']
+  aws.tags['Name'] = vconfig['aws_tags_name']
+  aws.ami = vconfig['aws_ami']
+
+  override.ssh.username = vconfig['aws_ssh_username']
+  override.ssh.private_key_path = vconfig['aws_ssh_private_key']
+end
+```
+
+Add the `AWS_ACCESS_KEY_ID` and the `AWS_SECRET_ACCESS_KEY` environment variables to your shell.
+
+Then run `vagrant up --provider=aws` to provision the instance.
+
+_For additional configuration options read the [Vagrant AWS Provider's README](https://github.com/mitchellh/vagrant-aws#readme)._
+
+### Example: Using Drupal VM behind a corporate proxy with `vagrant-proxyconf`
+
+Add the following variables to your `config.yml`.
+
+```yaml
+proxy_http: 'http://192.168.0.2:3128/'
+proxy_https: 'http://192.168.0.2:3128/'
+proxy_ftp: 'http://192.168.0.2:3128/'
+proxy_none: 'localhost,127.0.0.1,{{ drupal_domain }}'
+```
+
+Create a `Vagrantfile.local` in the root directory of your project.
+
+```ruby
+if Vagrant.has_plugin?('vagrant-proxyconf')
+  config.proxy.http = vconfig['proxy_http']
+  config.proxy.https = vconfig['proxy_https']
+  config.git_proxy.http = vconfig['proxy_http']
+  config.proxy.no_proxy = vconfig['proxy_none']
+  config.proxy.ftp = vconfig['proxy_ftp']
+end
+```
+
+_For additional configuration options read [Vagrant Proxyconf's README](https://github.com/tmatilai/vagrant-proxyconf#readme)._