Acquia currently recommends the use of either:
- Drupal VM: an isolated virtual machine, built with Vagrant and Ansible
- Acquia Dev Desktop: a turn-key LAMP stack tailored specifically for Acquia-hosted Drupal sites
- Alternative local development environments
No matter what local environment you choose to use, the following guidelines should be followed:
- In order to guarantee similar behavior, use Apache as your web server
- If your project is hosted on Acquia Cloud, please ensure to match our software versions
Using Drupal VM for BLT-generated projects¶
To use Drupal VM with a Drupal project that is generated with BLT:
brew tap caskroom/cask brew install php71 git composer ansible drush brew cask install virtualbox vagrant
Create & boot the VM
Commit all resulting files, including
git add -A git commit -m <your commit meessage>
Install Drupal and finalize BLT setup
vagrant ssh blt setup
Login to Drupal
There are also other changes you can make if you choose to match the Acquia Cloud server configuration more closely. See Drupal VM's example configuration changes in Drupal VM's
Subsequently, you should use
vagrant commands to interact with the VM. Do not re-run
blt vm. For instance, use
vagrant up to start the VM, and
vagrant halt to stop it.
Note: With a Drupal VM setup, BLT expects all commands (with the exception of commands in the
blt vm namespace), to be executed within the VM. To SSH into the VM, simply run
vagrant ssh as you did in the "Install Drupal" step above.
Drupal VM and Behat tests¶
Using the Drupal Extension's "drupal" driver with Drupal VM¶
The Drupal Extension for Behat has an inherent limitation: it cannot use the 'drupal' driver to bootstrap Drupal on a remote server. If you're using Drupal VM and would like to execute Behat tests using the 'drupal' driver, you must execute them from within the VM. This is a break of the established pattern of running all BLT commands outside of the VM.
To execute Behat tests using the 'drupal' driver on a Drupal VM environment, you must do the following:
- SSH into the VM
- Execute behat tests
Alternatively, you may choose to write only behat tests that utilize the Drupal Extension's "drush" driver. Doing this will allow you to run
blt tests:behat:run from the host machine.
Using Acquia Dev Desktop for BLT-generated projects¶
Project creation and installation changes¶
- Add a new site in Dev Desktop by selecting Import local Drupal site. Point it at the
docrootfolder inside your new code base. Your
/sites/default/settings.phpfile will be modified automatically to include the Dev Desktop database connection information.
- Follow the normal setup process by executing
In order to use a custom version of Drush (required by BLT) with Dev Desktop, you must:
Add the following lines to
~/.bash_profile(or equivalent file):
export PATH="/Applications/DevDesktop/mysql/bin:$PATH" export DEVDESKTOP_DRUPAL_SETTINGS_DIR="$HOME/.acquia/DevDesktop/DrupalSettings"
Ensure that Dev Desktop's PHP binary is being used on the CLI. This will require adding a line like this to your
The exact line will depend upon the version of PHP that you intend to use. You can check the effect of this value via
Enable the usage of environmental variables by adding the following line to
php.ini, which you can locate with
variables_order = "EGPCS"
Restart your terminal session after making the aforementioned changes.
- Optionally, run
blt doctorto verify your configuration.
Alternative local development environments¶
Some teams may prefer to use a different development environment. Drupal VM offers a great deal of flexibility and a uniform configuration for everyone, but sometimes a tool like Acquia Dev Desktop, MAMP/XAMPP, or a different environment (e.g., a bespoke Docker-based dev environment) may be preferable.
It is up to each team to choose how to handle local development, but some of the main things that help a project's velocity with regard to local development include:
- Uniformity and the same configuration across all developer environments
- Ease of initial environment configuration (if it takes more than an hour to get a new developer running your project locally, you're doing it wrong)
- Ability to emulate all aspects of the production environment with minimal hassle (e.g., Varnish, Memcached, Solr, Elasticsearch, different PHP versions, etc.)
- Helpful built-in developer tools (e.g., XHProf, Xdebug, Adminer, PimpMyLog)
- Ease of use across Windows, Mac, or Linux workstations
If you choose to use a different solution than recommended here, please make sure it fits all the needs of your team and project, and will not be a hindrance to project development velocity!
While the BLT team cannot officially support these alternative environments, please submit documentation of any special steps necessary with the tool you choose so that others can learn from your experience. Environments for which others have contributed tips include: - Lando