Install a Vagrant environment into a Drupal project.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin
conf
tasks
.gitignore
CHANGELOG.md
README.md
composer.json

README.md

"The" Vagrant

Add a customizable vagrant environment into a 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 our current VM-based development environment.

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

Dependencies

This Vagrant configuration requires the following plugins:

This setup will use a version 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.

Installation

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

  1. Require the palantirnet/the-vagrant package
  2. Run the-vagrant's install script to add and configure the Vagrantfile

Require the palantirnet/the-vagrant package with composer

$> composer require palantirnet/the-vagrant

Runing the install script

  1. From within your project, run vendor/bin/the-vagrant-installer
  2. This will prompt you for project-specific configuration:
  • The project hostname
  • The project web root
  • Enable Solr
  • Enable HTTPS
  • Make a project-specific copy of the Ansible roles and a copy of the default playbook
  • OR make a project-specific Ansible playbook to be run in addition to the default playbook
  1. Check in and commit the new Vagrantfile to git

You can re-run the install script later if you need to change your configuration.

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

  1. Re-run the install script: vendor/bin/the-vagrant-installer
  2. When you are prompted to copy the Ansible roles, reply n
  3. 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

  1. 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.
  2. Check in and commit this new provisioning directory and updated Vagrantfile to git
  3. Add or update the roles and playbook as necessary.

100% custom provisioning

  1. Re-run the install script: vendor/bin/the-vagrant-installer
  2. When you are prompted to copy the Ansible roles, reply Y:

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

  1. This will create a new provisioning directory in your project that contains the Ansible playbook and roles. Your Vagrantfile will refer to this playbook instead of the one in the vendor directory.
  2. Check in and commit this new provisioning directory and updated Vagrantfile to git
  3. Add or update the roles and playbook as necessary.

Tips for developing Ansible playbooks and roles

  • 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:

    1. Create a requirements.yml file at provisioning/requirements.yml
    2. 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. You can find more information about the specifics of accessing default software like MySQL, Solr, and Mailhog in the Drupalbox README.


Copyright 2016, 2017, 2018 Palantir.net, Inc.