README

Add a customizable vagrant environment into a Drupal project. This may be used in conjunction with the drupal-skeleton and the-build, or it may be used to retrofit an existing project with a VM-based development environment.

Note: If you are setting up a new project, you likely want to start with drupal-skeleton.

Why the-vagrant?

Start from a base box that comes with the basics installed for fast, consistent startup
Use a thin layer of configuration to set up your project, without masking Vagrant itself
Customize with Ansible playbooks when necessary
Separate your local development environment from your build tools

Dependencies

Vagrant >= 2.1.0
Vagrant plugins:
- vagrant-hostmanager
- vagrant-auto_network
Virtualbox >= 5.0
Ansible >= 2.9

Installation

To use the-vagrant on a project, you will need to:

Use composer to add the package to your project:

composer require --dev palantirnet/the-vagrant

Run the-vagrant's install script to add and configure the Vagrantfile:
```
vendor/bin/the-vagrant-installer
```

This will prompt you for project-specific configuration:
- The project hostname
- The project web root
- Enable Solr
- Enable HTTPS
- Add a project-specific Ansible playbook to be run in addition to the default playbook

Check in and commit the new Vagrantfile to git

If you need to change your configuration later, you can re-run the install script, or edit the Vagrantfile directly.

Updating

To update an existing installation of the-vagrant in a project, you will need to:

composer update palantirnet/the-vagrant
Follow any steps from the release notes.

Note: If you need to update the underlying VM (the Vagrant box drupalbox, which includes PHP, Apache, MySQL, and Solr), you will need to run vagrant destroy then vagrant box update and vagrant up. Updating the VM doesn't always require updating the-vagrant, and vice versa.

Customizing your environment

Several things can be configured during the interactive installation:

The project hostname
The project web root
Enable Solr
Enable HTTPS

A few more things can be customized directly in your Vagrantfile:

Extra hostnames for this VM (use this for multisite)
Extra apt packages to install
The PHP timezone

By default, the-vagrant references ansible roles from the package at vendor/palantirnet/the-vagrant/conf/vagrant/provisioning. If your project needs configuration beyond what is provided via in the Vagrantfile, you can re-run the install script and update the provisioning.

Run a custom playbook in addition to the defaults

Re-run the install script: vendor/bin/the-vagrant-installer
When you are prompted to copy the Ansible roles, reply n
When you are prompted to add an additional Ansible playbook to your project, reply Y

Copy Ansible roles into your project for customization (Y,n) [n]? n

OR add an additional Ansible playbook to your project (Y,n) [n]? Y

This will create a new provisioning directory in your project that contains a simple Ansible playbook and example role. Your Vagrantfile will refer to this playbook in addition to the one in the vendor directory.
Check in and commit this new provisioning directory and updated Vagrantfile to git
Add or update the roles and playbook as necessary.

Tips for developing Ansible playbooks and roles

The Ansible documentation has an Intro to Playbooks

Check the syntax of a playbook:

  ansible-playbook --syntax-check provisioning/my_playbook.yml

Run a playbook against a Vagrant box without re-provisioning the box:

  ansible-playbook -u vagrant -i .vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory provisioning/my_playbook.yml

Debug step outputs and variables within a role using the debug module:

  - name: Some command
    command: ls
    register: my_command_output
  - name: Some debugging
    debug:
      var: my_command_output

Add third-party roles from Ansible Galaxy:

Create a requirements.yml file at provisioning/requirements.yml
Configure the ansible.galaxy_role_file and ansible.galaxy_roles_path properties for the custom playbook in your Vagrantfile:

  if (defined?(ansible_custom_playbook) && !ansible_custom_playbook.empty?)
      config.vm.provision "myproject-provision", type: "ansible" do |ansible|
          ansible.playbook = ansible_custom_playbook
          ansible.galaxy_role_file = "provisioning/requirements.yml"
          ansible.galaxy_roles_path = "provisioning/roles/"
      end
  end

In the Vagrantfile, pass additional configuration through to the Ansible provisioners. A great use case for this is setting the php_ini_memory_limit when using the default palantirnet/the-vagrant provisioning:

  ansible.extra_vars = {
    "project" => project,
    "hostname" => hostname,
    "extra_hostnames" => extra_hostnames,
    "solr_enabled" => ansible_solr_enabled,
    "https_enabled" => ansible_https_enabled,
    "project_web_root" => ansible_project_web_root,
    "timezone" => ansible_timezone,
    "system_packages" => ansible_system_packages,
    "php_ini_memory_limit" => "512M",
  }

Default Software

the-vagrant uses Vagrant boxes built with palantirnet/devkit. Releases of this Vagrant base box are on Vagrant Cloud. You can find more information about the specifics of accessing default software like MySQL, Solr, and Mailhog in the Drupalbox README.

Compatibility between the-vagrant and base boxes

Some versions of the-vagrant are coordinated with releases of the palantir/drupalbox Vagrant box:

the-vagrant version	palantir/drupalbox version	Vagrant provider	Vagrant version
2.2.0	>= 1.2.0, < 2.0	virtualbox	>= 2.1.0
2.1.0	>= 1.2.0, < 2.0	virtualbox
2.0.1	1.1.1, 1.2.0	virtualbox
2.0.0	1.1.0, 1.1.1	virtualbox, vmware_desktop (drupalbox v1.1.0 only)
0.6.0 - 1.1.1	>= 0.2.4, < 1.0	virtualbox, vmware_desktop

* Note that version 1.2.0 of the palantir/drupalbox VM requires updating to version 2.0.1 of palantirnet/the-vagrant.

palantirnet / the-vagrant

Maintainers

Details