A VM for Drupal development
Drupal VM is a VM for Drupal, built with Ansible.
Drupal VM makes building Drupal development environments quick and easy, and introduces developers to the wonderful world of Drupal development on virtual machines or Docker containers (instead of crufty old MAMP/WAMP-based development).
There are two ways you can use Drupal VM:
The rest of this README assumes you're using Vagrant and VirtualBox (this is currently the most flexible and widely-used method of using Drupal VM). If you'd like to use Drupal VM with Docker, please read the Drupal VM Docker documentation.
Drupal VM installs the following on an Ubuntu 18.04 (by default) linux VM:
It should take 5-10 minutes to build or rebuild the VM from scratch on a decent broadband connection.
Please read through the rest of this README and the Drupal VM documentation for help getting Drupal VM configured and integrated with your workflow.
Full Drupal VM documentation is available at http://docs.drupalvm.com/
There are a couple places where you can customize the VM for your needs:
config.yml: Override any of the default VM configuration from
default.config.yml; customize almost any aspect of any software installed in the VM (more about configuring Drupal VM.
drupal.make.yml: Contains configuration for the Drupal core version, modules, and patches that will be downloaded on Drupal's initial installation (you can build using Composer, Drush make, or your own codebase).
If you want to use Drupal 8 on the initial install, do the following:
drupal_composer_project_package: "drupal/recommended-project:^[email protected]"inside
If you want to use Drupal 7 on the initial install, do the following:
This Quick Start Guide will help you quickly build a Drupal 9 site on the Drupal VM creating a new Composer project. You can also use Drupal VM with Composer, a Drush Make file, with a Local Drupal codebase, or even a Drupal multisite installation.
If you want to install a Drupal site locally with minimal fuss, just:
cdinto this project directory and run
But Drupal VM allows you to build your site exactly how you like, using whatever tools you need, with almost infinite flexibility and customization!
You can also use an alternative provider like Parallels or VMware. (Parallels Desktop 11+ requires the "Pro" or "Business" edition and the Parallels Provider, and VMware requires the paid Vagrant VMware integration plugin).
vagrant plugin install vagrant-vbguest.
config.ymland modify it to your liking.
cdto this directory (containing the
Vagrantfileand this README file).
vagrant up, and let Vagrant do its magic.
Once the process is complete, you will have a Drupal codebase available inside the
drupal/directory of the project.
Note: If there are any errors during the course of running
vagrant up, and it drops you back to your command prompt, just run
vagrant provisionto continue building the VM from where you left off. If there are still errors after doing this a few times, post an issue to this project's issue queue on GitHub with the error.
Open your browser and access http://drupalvm.test/. The default login for the admin account is
adminfor both the username and password.
Note: By default Drupal VM is configured to use
192.168.88.88as its IP, if you're running multiple VM's the
vagrant plugin install vagrant-auto_network) can help with IP address management if you set
By default, this VM includes the extras listed in the
installed_extras: - adminer # - blackfire # - drupalconsole - drush # - elasticsearch # - java - mailhog # - memcached # - newrelic # - nodejs - pimpmylog # - redis # - ruby # - selenium # - solr # - tideways # - upload-progress - varnish # - xdebug # - xhprof
If you don't want or need one or more of these extras, just delete them or comment them from the list. This is helpful if you want to reduce PHP memory usage or otherwise conserve system resources.
Drupal VM is built to integrate with every developer's workflow. Many guides for using Drupal VM for common development tasks are available on the Drupal VM documentation site.
Drupal VM follows semantic versioning, which means your configuration should continue working (potentially with very minor modifications) throughout a major release cycle. Here is the process to follow when updating Drupal VM between minor releases:
config.ymlvariables mentioned therein.
config.ymlwith the updated
curl https://raw.githubusercontent.com/geerlingguy/drupal-vm/master/default.config.yml | git diff --no-index config.yml -).
vagrant provisionto provision the VM, incorporating all the latest changes.
For major version upgrades (e.g. 4.x.x to 5.x.x), it may be simpler to destroy the VM (
vagrant destroy) then build a fresh new VM (
vagrant up) using the new version of Drupal VM.
Drupal VM runs on almost any modern computer that can run VirtualBox and Vagrant, however for the best out-of-the-box experience, it's recommended you have a computer with at least:
vagrant haltin the Terminal in the same folder that has the
Vagrantfile. To destroy it completely (if you want to save a little disk space, or want to rebuild it from scratch with
vagrant upagain), type in
vagrant ssh. You can also get the machine's SSH connection details with
vagrant destroyand then another
vagrant up), make sure you clear out the contents of the
drupalfolder on your host machine, or Drupal will return some errors when the VM is rebuilt (it won't reinstall Drupal cleanly).
To run basic integration tests using Docker and Molecule:
pip3 install ansible molecule[docker]
The project's automated tests are run via GitHub Actions, and the more comprehensive test suite covers multiple Linux distributions and many different Drupal VM use cases and deployment techniques.
This project is licensed under the MIT open source license.