How to Get Started with Acquia BLT on Ubuntu

Introduction

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.

Prerequisites

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:

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

Now configure Git and set up your name and email.

Setting Up Local via Vagrant

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

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 (https://github.com/lando/lando/releases)
   2. Install ADS using the following command

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 https://github.com/your-org/<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.

Setting Up the Local Environment

Begin setting up your local environment by going to the cloned directory and running 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

2. SSH into VM

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

Using Acquia Dev Studio with Lando

1. Start the container 

2. SSH into container

3. Run 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:

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

Running Drupal Update

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

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

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

Running PHPUnit tests

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

` or in short `blt tpr`.

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

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

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

Replace <uri> with projects local uri example local.project.com

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

5. 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

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

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

8. On GitHub, navigate to the main page of the repository.
9. In the "Branch" menu, choose the branch that contains your commits.
   
10. To the right of the Branch menu, click New pull request.
    
11. 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.
    
12. Type a title and description for your pull request.
    
13. 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."
    
14. 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.