How to Get Started with Acquia BLT on Ubuntu


This blog is a step-by-step guide for developers to set up a project enabled with Acquia Build and Launch Tool (BLT) on their local Ubuntu machine. BLT is a powerful tool that helps dev teams implement Drupal best practices (automated testing, CI, CD, coding standards) across all of their Drupal projects and Acquia cloud hosting environments. You can also extend BLT with custom BLT commands to perform operations specific to your project.

In order to onboard an Acquia BLT project with a fresh Ubuntu installation, you first need to install some prerequisites.

We’ll also go in-depth on the steps and guidelines for development using Acquia BLT. This document is prepared on Ubuntu 18.04 but you can use similar steps on other versions of Ubuntu and other Linux distributions.


  1. PHP
  2. Composer 
  3. Git
  4. Vagrant/Docker as your preference.
  5. Editor/IDE of your choice

PHP, Composer and Git

You don’t need a full LAMP stack, because you are going to use either DrupalVM or ADS (Acquia Dev Studio), hence you don’t need Apache as BLT recommends using DrupalVM or Docker for local setup. You will also need Composer and Git. Run following command to install the required packages:

sudo apt-get install php composer git php-dom php-phar php-mbstring php-curl php-gd php-xdebug php-xml php-mysql

Depending on your project you may need some additional PHP extensions.

Now configure Git and set up your name and email.

git config --global "Test user"
git config --global "[email protected]"

Setting Up Local via Vagrant

Vagrant is available in default repo. You can install it using apt-get.

sudo apt-get install vagrant

Setting Up Local via Docker and Acquia Dev Studio (ADS) with Lando

Acquia Dev Studio (ADS) is a suite of tools that streamlines and accelerates Drupal site building by providing a suite of tools in a single command, including Acquia Lightning, , BLT, Lando and Acquia Pipelines. Dev Studio is not required to install BLT (you can also use Acquia Dev Desktop or DDEV if you prefer) but Dev Studio can enhance your BLT experiences and automate much of the typical workflow.   

  1. For docker please follow the official instructions 
  2. Install ADS and Lando
    1. Download and install the latest stable version of Lando from Github (
    2. Install ADS using the following command

curl | bash

Getting Started

The following steps are based on Acquia BLT, an open source project template and tool that enables building, testing and deploying Drupal installations following Acquia Professional Services’ best practices. While this is one of many methodologies, it is our recommended process.

  1. Review the Required / Recommended Skills for working with a BLT project.
  2. Ensure that your computer meets the minimum installation requirements (and then install the required applications). See the System Requirements.
  3. Request access to the organization that owns the project repo in GitHub (if needed).
  4. Fork the project repository in GitHub at<project>
  5. Request access to the Acquia Cloud Environment for your project (it is required to sync Drush aliases and site).
  6. Setup an SSH key that can be used for GitHub and the Acquia Cloud (you CAN use the same key).
    1. Setup GitHub SSH Keys
    2. Setup Acquia Cloud SSH Keys

Clone your forked repository. By default, Git names this "origin" on your local.

git clone [email protected]:username/project-repo.git
git remote add upstream [email protected]:your-org/project-repo.git

Setting Up the Local Environment

Begin setting up your local environment by going to the cloned directory and running composer install.  

cd project-repo

composer install

There are multiple ways you can set up on your local machine:

  1. Using a local apache server (not recommended)
  2. Drupal-VM using vagrant
  3. Docker using Lando

Using Drupal VM

BLT comes with inbuilt support for Drupal VM, to initialize the project do the following steps

  1. Initialize VM

vagrant up

  1. SSH into VM

vagrant ssh

  1. Run BLT setup command to set up the site.

blt setup

Using Acquia Dev Studio with Lando

  1. Start the container 

ads start

  1. SSH into container

lando ssh

  1. Run blt setup

blt setup

BLT is extremely valuable to standardize complex processes through reducing the potential for user error and lengthy review cycles. BLT lets you automatically apply multiple tools in a single command and offers straightforward deployment and synching with all of your different environments (local, dev, staging, prod) without a bunch of unnecessary legwork. Let’s look at the set of commands you’ll get when you install BLT: 

Common Commands

  1. Update aliases
  2. Running Drupal updates
  3. Blt Sync
  4. Running PHPUnit tests

Before running these commands, you need to SSH into the VM or Docker containers as mentioned in the previous section.

Update Aliases

Before updating aliases ,make sure you have access to the Acquia Site Factory project and add your SSH key on Acquia Cloud Platform. To import Drush aliases, run the following command:

blt aliases

Please note: If you are using BLT version 11 or later you’ll need an additional package before this command.

composer require lcatlett/blt-drush-alias

Running Drupal Update

The `blt drupal:update` in short `blt du` command run database update and import the configurations changes if any.

blt drupal:update

BLT Sync

The BLT sync command is used for syncing your local site with one of the sites on the Dev/Stage or Prod environment based on the setting in bly.yml file

blt sync

If you want to sync with a site not mentioned in blt.ym file, you need to pass the site alias as parameter 

blt sync -D drush.aliases.remote=site1.01live && drush rsync @site1.01live:%files @self:%files

Running PHPUnit tests

To run PHPUnit tests, assuming PHPUnit is configured correctly.Rune `blt tests:phpunit:run 

` or in short `blt tpr`.

blt tests:phpunit:run

Steps to Add your Changes and Raise a Pull Request

The following steps are for a basic example to work on JIRA tickets and raising a Pull Request (PR)

  1. Create a feature branch from the base branch eg: develop. The naming of the feature branch should same as the JIRA ticket eg: PRJ-122

git checkout develop -b PRJ-1225

  1. For this  example, we will add a contributed module to the project eg:  recaptcha
    Using Composer:

composer require 'drupal/recaptcha:^3.0'

  1. Once the contributed module is added to the project we will enable it using the drush command.

vagrant ssh
drush en recaptcha -l <uri>

Replace <uri> with projects local uri example

  1. After the module is enabled, the configuration should be updated. 

drush cex -l <uri> -y

  1. The above command will update core.extensions.yml and lightning.extensions.yml file in docroot/config
    Commit these files along with composer.json and composer.lock file

git add docroot/config/default/core.extension.yml docroot/config/default/lighting.extension.yml composer.json composer.lock
git commit -m “PRJ-1225: Add recaptcha module.”

  1. Before pushing the branch to our fork on remote origin, we must validate the code using the following BLTcommand

blt validate

  1. Fix any errors shown above and validate command. Commit those changes, then push the branch to your fork.

git push origin PRJ-1225

  1. On GitHub, navigate to the main page of the repository.
  2. In the "Branch" menu, choose the branch that contains your commits.
    Branch dropdown menu
  3. To the right of the Branch menu, click New pull request.
    Pull Request button
  4. Use the base branch drop-down menu to select the branch you'd like to merge your changes into, then use the compare branch drop-down menu to choose the topic branch you made your changes in.
    Drop-down menus for choosing the base and compare branches
  5. Type a title and description for your pull request.
    Pull request title and description fields
  6. To create a pull request that is ready for review, click “Create Pull Request”. To create a draft pull request, use the drop-down, and select “Create Draft Pull” Request, then click “Draft Pull Request”. For more information about draft pull requests, see "About pull requests."
    Create pull request button
  7. Once the PR is raised, copy the URL of the PR and submit it in a comment on the JIRA ticket, move the JIRA ticket to the next state eg: ready for review.

And there you have it! Once you have BLT up and running you  can begin taking advantage of the powerful automation capabilities and project template features to create and deploy your Drupal projects, push updates to your existing sites.