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
- PHP
- Composer
- Git
- Vagrant/Docker as your preference.
- 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 user.name "Test user" |
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.
- For docker please follow the official instructions
- Install ADS and Lando
- Download and install the latest stable version of Lando from Github (https://github.com/lando/lando/releases)
- Install ADS using the following command
curl https://downloads.acquia.studio/install-standalone.sh | 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.
- Review the Required / Recommended Skills for working with a BLT project.
- Ensure that your computer meets the minimum installation requirements (and then install the required applications). See the System Requirements.
- Request access to the organization that owns the project repo in GitHub (if needed).
- Fork the project repository in GitHub at https://github.com/your-org/<project>
- Request access to the Acquia Cloud Environment for your project (it is required to sync Drush aliases and site).
- Setup an SSH key that can be used for GitHub and the Acquia Cloud (you CAN use the same key).
Clone your forked repository. By default, Git names this "origin" on your local.
git clone [email protected]:username/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:
- Using a local apache server (not recommended)
- Drupal-VM using vagrant
- Docker using Lando
Using Drupal VM
BLT comes with inbuilt support for Drupal VM, to initialize the project do the following steps
- Initialize VM
vagrant up |
- SSH into VM
vagrant ssh |
- Run BLT setup command to set up the site.
blt setup |
Using Acquia Dev Studio with Lando
- Start the container
ads start |
- SSH into container
lando ssh |
- 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
- Update aliases
- Running Drupal updates
- Blt Sync
- 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)
- 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 |
- For this example, we will add a contributed module to the project eg: recaptcha
Using Composer:
composer require 'drupal/recaptcha:^3.0' |
- Once the contributed module is added to the project we will enable it using the drush command.
vagrant ssh |
Replace <uri> with projects local uri example local.project.com
- After the module is enabled, the configuration should be updated.
drush cex -l <uri> -y |
- 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 |
- Before pushing the branch to our fork on remote origin, we must validate the code using the following BLTcommand
blt validate |
- Fix any errors shown above and validate command. Commit those changes, then push the branch to your fork.
git push origin PRJ-1225 |
- On GitHub, navigate to the main page of the repository.
- In the "Branch" menu, choose the branch that contains your commits.
- To the right of the Branch menu, click New pull request.
- 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.
- Type a title and description for your pull request.
- 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."
- 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.