palantirnet / the-vagrant
Install a Vagrant environment into a Drupal project.
Installs: 45 516
Dependents: 0
Suggesters: 0
Security: 0
Stars: 2
Watchers: 34
Forks: 1
Open Issues: 9
Language:Ruby
Requires
- phing/phing: ^2.14
- dev-develop
- 3.x-dev
- 2.7.0
- 2.6.2
- 2.6.1
- 2.6.0
- 2.5.2
- 2.5.1
- 2.5.0
- 2.4.0
- 2.3.0
- 2.2.2
- 2.2.1
- 2.2.0
- 2.2.0-alpha2
- 2.2.0-alpha
- 2.1.0
- 2.0.1
- 2.0.0
- 1.1.1
- 1.1.0
- 1.0.0
- 0.7.1
- 0.7.0
- 0.6.0
- 0.5.1
- 0.5.0
- 0.4.0
- 0.3.0
- dev-79-issue-yarn-key-apt
- dev-default-to-node-12
- dev-release
- dev-separate-the-vagrant-settings
- dev-release-1.x
This package is auto-updated.
Last update: 2022-10-29 02:01:16 UTC
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:
- 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. YourVagrantfile
will refer to this playbook in addition to the one in thevendor
directory. - Check in and commit this new
provisioning
directory and updatedVagrantfile
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
andansible.galaxy_roles_path
properties for the custom playbook in yourVagrantfile
:
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
- Create a requirements.yml file at
-
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 defaultpalantirnet/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.
Copyright 2016 - 2020 Palantir.net, Inc.