docs

drupalvm-in-subdirectory.md

To make it easier bringing in Drupal VM updates to an existing project, you might consider a slightly more complex setup. Instead of mixing your project's files with Drupal VM's configuration files, you can separate the two with the help of a delegating Vagrantfile.

Add Drupal VM to your project

There are many ways you can provide the Drupal VM code and we will go through how to configure things both if you're using composer and if you're not.

Drupal VM as a composer dependency

Currently Drupal VM does not identify itself as composer package but you can still add it as a custom package. Add the package to the repositories array in composer.json

        {
            "type": "package",
            "package": {
                "name": "geerlingguy/drupal-vm",
                "version": "2.5.1",
                "source": {
                    "url": "https://github.com/geerlingguy/drupal-vm.git",
                    "type": "git",
                    "reference": "origin/2.5.1"
                }
            }
        }

Then require it as a development package by adding:

    "require-dev": {
        "phpunit/phpunit": "~4.8",
        ...
        "geerlingguy/drupal-vm": "~2.5"
    },

Drupal VM without composer

If you don't use composer in your project you can download Drupal VM (or add it as a git submodule) to any subdirectory in your project. In our examples we will name that subdirectory box/

├── docroot/
│   ├── ...
│   └── index.php
└── box/
    ├── ...
    ├── example.config.yml
    └── Vagrantfile

Setup your configuration files

Add and configure the config.yml anywhere you like, in this example we'll place it in a config/ directory. If you're using build_makefile, this is also a good location for the drupal.make.yml file.

Note: This will be the directory where Drupal VM looks for other local configuration files as well. For example local.config.yml and Vagrantfile.local.

├── config/
│   ├── config.yml
│   ├── drupal.make.yml
│   ├── local.config.yml
│   └── Vagrantfile.local
├── docroot/
│   ├── ...
│   └── index.php
├── vendor/
│   ├── ...
│   └── geerlingguy/drupal-vm/
└── box/
    ├── ...
    ├── example.config.yml
    └── Vagrantfile

If you're using pre_provision_scripts, post_provision_scripts or drush_makefile_path you will also need to adjust their paths to take into account the new directory structure. The examples used in example.config.yml assume the files are located in the Drupal VM directory.

# Default.
drush_makefile_path: ../../drupal.make.yml
# With Drupal VM as a Composer dependency.
drush_makefile_path: ../../../../../config/drupal.make.yml
# Simple subdirectory.
drush_makefile_path: ../../../config/drupal.make.yml

post_provision_scripts:
  # Default.
  - "../../examples/scripts/configure-solr.sh"
  # With Drupal VM as a Composer dependency.
  - "../../../../../examples/scripts/configure-solr.sh"
  # Simple subdirectory.
  - "../../../examples/scripts/configure-solr.sh"

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.

# 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.
# If you're using composer:
ENV['DRUPALVM_DIR'] = "vendor/geerlingguy/drupal-vm"
# If you're using a simple subdirectory:
ENV['DRUPALVM_DIR'] = "box"

# 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.

If you're using Composer your project structure should now look like:

├── Vagrantfile
├── composer.json
├── config/
│   ├── config.yml
│   ├── drupal.make.yml
│   ├── local.config.yml
│   └── Vagrantfile.local
├── docroot/
│   ├── ...
│   └── index.php
└── vendor/
    ├── ...
    └── geerlingguy/
        └── drupal-vm/

While if you're using a box/ subdirectory it will look like:

├── Vagrantfile
├── config/
│   ├── drupal.make.yml
│   ├── config.yml
│   ├── local.config.yml
│   └── Vagrantfile.local
├── docroot/
│   ├── ...
│   └── index.php
└── box/
    ├── ...
    ├── example.config.yml
    └── Vagrantfile

Provision the VM

Finally provision the VM using the delegating Vagrantfile.

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.

@opdavies another benefit with the PR is that you can have it in an unmodified state (composer package, git submodule), with your config.yml outside that subdirectory.