Getting Started with Acquia BLT (Build & Launch Tool) for Drupal

Working with and deploying Drupal 8 applications can be a daunting task for those coming from Drupal version 6 or 7. This may be especially true for pushing updates to a site. Fortunately, there is a solution to this. We’ll examine the main differences between the older versions of Drupal and version 8. Then we’ll examine how you can use Acquia BLT (Build & Launch Tool) to effectively push updates to your site, as well as to improve efficiency and collaboration across Drupal projects.

Deployments in Drupal 8 vs Older Drupal Versions

In the old days, as a developer, you had a few options for pushing updates to your site:

• Use FTP (File Transfer Protocol) /SFTP (SSH File Transfer Protocol or Secure File Transfer Protocol)
• Push with Git/SVN (open-source version or revision control options) direct to server environment(s)
• Script/deploy artifacts with Drush make files. Drush is a command line shell and Unix scripting interface for Drupal.
• Work directly on the production server (ahhhh!)

This was all well and good because older web codebases generally had a small footprint, so you could make changes like adding a new module, or applying a patch rather quickly.

However, all of that changed with Drupal 8 and these methods were no longer viable. You can still use workflows like this but you will generally be at a disadvantage. Let’s see why that’s the case.

At a high level, Drupal 8 has a lot more moving parts due to some major changes that were introduced:

• Drupal 8 is now built on top of Symfony components
• A majority of the project has been rewritten from procedural to object-oriented code 
• External PHP packages and libraries can now be used
• The footprint of the project is much, much larger due to the vendor directory where external dependencies are stored

This means that it is no longer a sound idea for you to leverage FTP, version control, manual patching, or downloads of new packages. There is simply too much to manage when it comes to deploying code and managing dependencies (libraries necessary to make your page work).

Instead, one of the new tools you must use is Composer - a dependency manager for PHP projects. Composer will fetch and manage external PHP dependencies, like Symfony components, Solarium Solr client, or Behat for behavior-based testing. 

One of the first areas of trouble you may run into here is assuming you can control, deploy, and upgrade Drupal effectively with just Composer. From my experience, by simply downloading the vanilla Drupal release from drupal.org, the most you will be able to do effectively is fetch modules with Composer and build the manifest file. This is because the public releases available on drupal.org do not currently require or enforce you to use a Composer-based workflow.

The road to creating a full-fledged deployment workflow on Drupal 8 is long but fortunately, Acquia has provided a tool, called BLT, to help you get up and running here.

Working with Acquia BLT

Acquia BLT is designed to improve the experience of creating projects with Drupal, maintaining those projects, deploying them, and aid in creating a set of workflow tools and processes for the development team.

Getting started with BLT is rather straightforward. You do not need to go to drupal.org and get Drupal itself, nor do you need to go there to get modules or themes anymore. All you need is the command line, and the latest version of Composer installed on the machine.

First, I would advise creating a folder on your machine such as ‘Sites’ in which to execute these commands. In this example, the new project will live at ‘Sites/mycompany/’ after composer completes.

Let’s assume you are starting a new project for "MyCompany". Here is how you can get the project setup with BLT:

composer clear-cache
export COMPOSER_PROCESS_TIMEOUT=2000
composer create-project --no-interaction acquia/blt-project mycompany
cd mycompany.com

First, you will need to flush the Composer cache to ensure you get the latest releases and not a cached version. Second, you’ll need to increase the process timeout because calculating and fetching dependencies is a pretty intensive process, and you want to ensure it has enough time to complete. (Both are shown in the commands above.)

composer run-script blt-alias
source ~/.bash_profile

BLT also comes with its own set of commands. The above commands install an alias for your terminal. Entering blt in the command line from a project then yields a whole host of commands you can run for your project like validating code, building a virtual machine, deploying code, running tests, syncing files, and syncing databases.

Creating a Virtual Machine

The next thing you are going to need is a place to install Drupal and run it. My weapon of choice here has been DrupalVM for the last few years. Acquia BLT comes with great support for DrupalVM.

Using blt, we can create a virtual machine via DrupalVM:

blt vm

If you want to configure the VM, choose to not boot the VM at the end of this command. It will generate a configuration file that the VM uses when provisioning. This file, located at 'box/config.yml' in your project, can be edited to your liking.

Here is a sample of it:

# Update the hostname to the local development environment hostname.
vagrant_hostname: local.mycompany.com
vagrant_machine_name: mycompany.com

# Set the IP address so it doesn't conflict with other Drupal VM instances.
vagrant_ip: 0.0.0.0

# Use Ubuntu 16.04 LTS to match Acquia Cloud environments.
vagrant_box: geerlingguy/ubuntu1604

# Set drupal_site_name to the project's human-readable name.
drupal_site_name: "MyCompany Website"

# Provide the path to the project root to Vagrant.
vagrant_synced_folders:
  # Set the local_path for the first synced folder to `.`.
  - local_path: .
    # Set the destination to the Acquia Cloud subscription machine name.
    destination: /var/www/mycompany.com
    type: nfs

drupal_build_composer_project: false
# Toggling this to `true` would invoke `composer install` with the
# projects own `composer.json` successfully.
drupal_build_composer: false
drupal_composer_path: false
drupal_composer_install_dir: "/var/www/mycompany.com"
drupal_core_path: "/var/www/mycompany.com/docroot"
ssh_home: /var/www/mycompany.com

drupal_db_user: drupal
drupal_db_password: drupal
drupal_db_name: drupal

# Set this to 'false' if you don't need to install drupal (using the drupal_*
# settings below), but instead copy down a database (e.g. using drush sql-sync).
drupal_install_site: false

# Drupal VM automatically creates a drush alias file in your ~/.drush folder if
# this variable is 'true'.
configure_drush_aliases: false

# This is required for front-end building tools.
nodejs_version: "4.x"
nodejs_npm_global_packages:
  - name: bower
  - name: gulp-cli
nodejs_install_npm_user: "{{ drupalvm_user }}"
npm_config_prefix: "/home/{{ drupalvm_user }}/.npm-global"
installed_extras:
  - adminer
  - drush
  - mailhog
  - nodejs
  - selenium
  - xdebug

# PHP 5.6 (PHP 7.1 is being tested, see: https://docs.acquia.com/node/25726).
php_version: "5.6"
php_packages_extra:
  - "php{{ php_version }}-bz2"
  - "php{{ php_version }}-imagick"
  - imagemagick

# XDebug configuration.
# Change this value to 1 in order to enable xdebug by default.
php_xdebug_default_enable: 0
php_xdebug_coverage_enable: 0
# Change this value to 1 in order to enable xdebug on the cli.
php_xdebug_cli_enable: 0
php_xdebug_remote_enable: 1
php_xdebug_remote_connect_back: 1
# Use PHPSTORM for PHPStorm, sublime.xdebug for Sublime Text.
php_xdebug_idekey: PHPSTORM
php_xdebug_max_nesting_level: 256
php_xdebug_remote_port: "9000"
php_memory_limit: "512M"

post_provision_scripts:
  - "../../../acquia/blt/scripts/drupal-vm/post-provision.sh"

You're free to change these values to suit your project. For example, if you have the Vagrant Autonetwork plugin installed, which lets Vagrant determine an IP to use for the machine instead of hardcoding one in, you can simply edit the vagrant_ip value:

# Set the IP address so it doesn't conflict with other Drupal VM instances.
vagrant_ip: 0.0.0.0

BLT sets the default PHP version to 5.6 to be compatible with the Acquia Cloud environment, but you can swap that for PHP 7.1:

# PHP Configuration. Currently-supported versions: 5.6, 7.0, 7.1.
# See version-specific notes: http://docs.drupalvm.com/en/latest/configurations/php/
php_version: "7.1"
php_install_recommends: no
php_memory_limit: "256M"
php_display_errors: "On"
php_display_startup_errors: "On"
php_realpath_cache_size: "1024K"
php_sendmail_path: "/opt/mailhog/mhsendmail"
php_opcache_enabled_in_ini: true
php_opcache_memory_consumption: "192"
php_opcache_max_accelerated_files: 4096
php_max_input_vars: "4000"

Will your project need Solr, Redis/Memcache, Varnish or NodeJS? No problem, you can add them, too:

installed_extras:
  - redis
  - nodejs
  - solr
  - xdebug

There are a whole host of things you can tailor for the VM. For more information, refer to the documentation for DrupalVM.

When you're done modifying the file, you can start the machine:

vagrant up

Installing Drupal

Now that you have your virtual machine running with all of your required components (Linux, Apache, MySQL and PHP), you can install Drupal.

BLT also generates a control file under blt/project.yml which dictates what happens to the project under different phases / command execution.

By default, BLT will instruct Drupal to be installed using the Lightning profile distribution. If you want to change this and install using the vanilla standard profile, you can edit the project details in this file and change the profile value to standard:

project:
  machine_name: mycompany.com
  prefix: BLT
  human_name: 'MyCompany Website'
  profile:
    name: standard
  local:
    protocol: http
    hostname: 'local.${project.machine_name}.com'

You can also edit the human_name value from the default, too.

From here, you can complete the setup by running the setup command in the command line:

blt setup

This command will download the latest release of Drupal, install it, and run various setup tasks. This step will also generate a username and password for the root user in Drupal, so be sure to take note of this. Otherwise, you will need to change these values with Drush, and/or use Drush to log in with the uli command.

Configuration import directory ../config/default does not contain any configuration; will skip import. [warning]
You are about to DROP all tables in your 'drupal' database. Do you want to continue? (y/n): y
Starting Drupal installation. This takes a while. Consider using the --notify global option. [ok]
Installation complete.  User name: _nU29Pqw1y  User password: bHDrSwd6wm [ok]
Congratulations, you installed Drupal! [status]
[Acquia\Blt\Robo\Tasks\DrushTask] Done in 35.263s

From start to finish, this only takes around five minutes to get a project up and running. You now have a solid project structure with Drupal installed and ready to go. At this point, you can commit your project to your git repo. Other teammates grabbing the code will only have to run vagrant up and composer install.

One of the bonuses of BLT is that it comes with a robust .gitignore file for you, so there is nothing to configure as far as that goes. However, it does ignore Drupal core and vendor directories. These are not tracked because they don't need to be. The composer.json and composer.lock files contain our build blueprint, so simply running composer install will build the project to these specifications.

In future installments, we’ll see how Acquia BLT can be leveraged to run front-end tasks, build an artifact, deploy a project, manage patches, and leverage continuous integration.

Do you have experience with using Acquia BLT (Build & Launch Tool) for Drupal? Join the discussion below via the comments.