Note
Acquia will end support for BLT on December 31, 2024. For more information on how to replace your BLT implementation with updated functionality, see You don’t need BLT on Acquia Cloud.
This document is intended for developers who have joined a project that already has BLT installed. It is a quick-start guide for getting your local development environment set up and getting oriented with the project standards and workflows.
If you are attempting to add BLT to a project or create a new BLT-based project, do not use this document. Instead, refer to Installing BLT.
Before you start
If you have been directed to this documentation by a project that’s using BLT to accelerate its development, testing, and deployment, we recommend exploring all of the BLT documentation first. Here’s what’s most important to do and know before getting started:
- BLT is distributed as a Composer package. This means that the project you are working on requires BLT as a dependency in its
composer.jsonfile. This also means that you don’t need to install or configure BLT globally on your computer, or as a separate tool—runcomposer installon the parent project and install a bash alias (as described below), and you’re ready to go. - You will need some project-specific information to set up your local environment, specifically whether you are using a virtual development environment (for example, Cloud IDE), and the name of your mainline development branch (
developormain). This should be referenced in your project’s README file. - If you need help, talk to your project team first, since they may have already encountered any issue you are experiencing. Then post an issue in the BLT issue queue. The issue queue isn’t only for bugs—we welcome feedback on all aspects of the developer experience.
- Verify that your local system and network meet the BLT system requirements. Also ensure that you have dependencies installed for any virtual development environment.
- Since BLT makes use of a variety of best practice development tools and processes (including Composer and Git), you should verify that you have the necessary skillset to develop with BLT.
Initial set up
- Fork the primary GitHub repository for the project you are developing.
Clone your fork to your local computer. By convention, BLT refers to your fork as
originand the primary repository asupstream):git clone [email protected]:username/project-repo.git git remote add upstream [email protected]:acquia-pso/project-repo.git
If your project uses separate
mainanddevelopbranches, checkout thedevelopbranch:git checkout develop
With Composer already installed, run the following command:
composer install
Install the BLT Launcher:
./vendor/bin/blt blt:init:shell-alias
At this point, restart your shell for the alias work.
Acquia recommends that you take advantage of one of the many virtual personal development workspaces that are available for development. Acquia recommends you to use Cloud IDE or local development solutions using the Acquia recipe.
You must run BLT commands inside the virtual environment. For example, if the project is utilizing Lando:
Start the VM:
lando start
Build and install Drupal:
lando blt setup
If your project does not use a personal development environment, or your terminal session is already running inside the container(s), BLT commands can be run without the Lando (or other) prefix.
For more information about setting up a local *AMP stack or virtual development environment, see Local development with BLT.
Ongoing development
As development progresses, you can use the following commands to reset your local environment (typically perform a git rebase and/or create a branch):
- Run
blt setupto rebuild the codebase, install a clean Drupal website from scratch, and run schema and configuration updates (most commonly used early in development). - Run
blt syncto rebuild the codebase, synchronize a database from a remote environment, and run schema and configuration updates (most commonly used later in development).
Each of these commands is a wrapper for several more granular commands that can be run individually if desired. For instance, blt sync runs blt drupal:update which runs the necessary Drush commands to update the database and import configuration. For a full list of available project tasks, run blt. For more information, see Project tasks.
Local Git configuration
For readability of commit history, set your name and email address properly:
git config user.name "Your Name"
git config user.email [email protected]
Ensure that your local email address correctly matches the email address for your JIRA account.
Updating your local environment
The project is configured to update the local environment with a local Drush alias and a remote alias as defined in blt/blt.yml or blt/local.blt.yml. Given that these aliases match those in drush/sites/, you can update the website with BLT.
GitHub configuration
To more easily identify developers in a project, be sure to set a name and profile picture in your GitHub profile.
When working with GitHub, the hub utility can be helpful when managing forks and pull requests. Installing hub can depend on your local environment, so follow the installation instructions accordingly.
Next steps
Review BLT developer and technical architect documentation by role to learn how to perform common project tasks and integrate with third party tools.