Adding sites to Drupal VM

Submitted by Webmaster on Friday, May 12, 2017 - 21:28

Drupal VM started as one of various virtual machine install scripts for Drupal development which run on Virtual Box. Because it was one of the best, and because of great support by geerlingguy (Jeff Geerling) it has become the default development environment for professional use. It provides a 'headless' Ubuntu virtual machine (nothing to do with headless Drupal!), with no desktop included. For those who want a Ubuntu desktop included with their VM, there is DrupalPro. This was a great tool but looks abandoned, although someone is offering an updated version, which I have not tried yet. The .ova file with the virtual machine image is in three 1.48GB .7z files on a file hosting service called 'Mega' which will require you to create a free account to dowload all three zip files.

Drupal VM is little more work to get started with it than with Acquia Dev Desktop, though it is better in several respects. One is that Dev Desktop includes drush, and allows you to run drush from command line on Windows, but does not include Drupal Console. Being a Ubuntu VM, Dev Desktop of course has the full range of Linux tools, and comes wiht a Drupal site pre-built with Composer.

Adding a new site to Dev Desktop is a matter of a few clicks. I wanted to a new site with Drupal VM. If you have plenty of disk space, and if you only want to work on one site at a time, it probably makes sense to create a new VM for every site. I decided to add a site to an existing copy of Drupal VM. There is a an issue on Github on how to do it, and it is not difficult. I share my quick recipe on how to do it, because I wasted a lot of time over what should be a simple task.


  1. Create a folder for your new project inside your drupal-vm folder (or whatever you call the synced folder between your host and guest machine: this is the folder with 'Vagrantfile' in it). It does not really matter whether you create this folder from your host machine or from within your VM. If you are running Windows 10, the latest install method for Drupal VM includes adding the Unix subsystem to Windows, so from the host machine you can use *nix commands. Assuming the new folder wil be called 'drupal8/', issue command: mkdir drupal8 from within your drupal-vm folder.
  2. Add virtual host to the config.yml file inside your drupal-vm folder. For example if you are using Apache within Drupal VM, and assuming your new sites document root is drupal8/, and your new site will be accessible in a browser on, add - servername: "" serveralias: "" documentroot: "/var/www/drupalvm/drupal8/web" extra_parameters: "{{ apache_vhost_php_fpm_parameters }}" In most cases there is no reason to create a separate php-fom pool. If you want to test the site on nginx, do something similar to the nginx virtualhosts block.
  3. The above step is where I got caught out. It wanted to let the Vagrantfile install my new site. Because there is a chain of path variables such as 'drupal_domain' which is not restricted to the config.yml, it becomes confusing unless you are very familiar with the structure. My experience was that hard coding the Drupal domain and sections of the path, as above, then manually issuing a Composer command to set up the site, loses nothing but a bit of elegance, and saves a lot of time.
  4. You will also want a new database. Assuming there is no reason why the new database should not share a user with the default site's database, that you are using mysql rather than postgres, and that the new database is going to be called 'drupal8', under the mysql_databases: section of config.yml add - name: "drupal8" encoding: utf8mb4 collation: utf8mb4_general_ci In this case you can use a variable for the database name without running into a complex chain of variables, although doing so may not contribute much.
  5. If there is no need to create a separate user for the database, you need to give your default database user access to the new database. For dev work there is no compelling reason not to give your database user full access, so you can change mysql_users: - name: "{{ drupal_db_user }}" host: "%" password: "{{ drupal_db_password }}" priv: "{{ drupal_db_name }}.*:ALL" to: mysql_users: - name: "{{ drupal_db_user }}" host: "%" password: "{{ drupal_db_password }}" priv: "*.*:ALL" Of course, having a single database user with access to all databases is not secure for production.
  6. Run 'vagrant provision'.
  7. Now log in to your VM, cd into the directory: cd /var/www/drupal-vm
  8. Provision your site with Composer: composer create-project drupal-composer/drupal-project:8.x-dev drupal8 --stability dev --no-interaction (assuming the folder for the new site is drupal8 and the web root set in your new virtualhost is /var/www/drupal-vm/drupal8/web).
  9. Remember to go the hosts file on your host machine and add the new domain to point to the Drupal VM. My hosts file at C:\Windows\System32\drivers\etc\hosts has
  10. It should now be possible to visit, or whatever you set the domain to be, in a browser and be taken to the install screen for the new site.

In case Drupal Console does not work for the new site, see this issue. In short, the cure is to run 'drupal self-update' from a non-Drupal directory such as /var/www/drupal-vm.

I am not an Ansible expert, and if there are better ways of doing things, of course I will welcome comments. Thanks for Jeff Geerling for his ongoing and excellent support for Drupal VM!