Creating a project with BLT

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.

Important

To use BLT, do not clone either BLT or the blt-project project.
The BLT project template is minimally maintained for backwards compatibility with BLT 11. If you are using BLT 12 or newer, you should instead add BLT to your preferred distribution or existing application: Adding BLT to an existing project.

To create a project that can utilize BLT:

Determine a machine name for your new project (such as my-project). For compatibility with third-party tools, Acquia recommends you use only letters, numbers, and hyphens for the machine name.

In a terminal window, run the following commands to create your project and download all dependencies (including BLT):

composer create-project --no-interaction acquia/drupal-recommended-project my-project
composer require acquia/blt

Change to your project directory. For example:
```
cd my-project
```
If this is your first time using BLT on this computer, restart your shell to allow Bash to detect the new BLT alias.
Customize your blt/blt.yml file to select an install profile. The build.yml file includes all available configuration values.

By default, BLT installs websites using the Drupal minimal profile. You can change this setting to any other core, contributed, or custom profile in your codebase.
Determine the personal developer workspace that is used on this project. Many of these tools; for example, Lando, DDev, require configuration files to be added or committed to the project repository. Once configured, start the container(s).
Install Drupal and generate any remaining required files, such as settings.php or hash salt by running the following command inside your container:
```
blt setup
```
Sign in to Drupal by running the following command inside your container:
```
drush @my-project.local uli
```
Be sure to replace my-project with the name of your project, which must be the value of project.machine_name in the blt/blt.yml file.

You now have a running local Drupal website that uses BLT.

For information about common instructions and how to begin using BLT, see Next steps with BLT.

Troubleshooting¶

If you have trouble creating the project, attempt to resolve the issue by using one of the following methods:

Clear the Composer cache.

Increase the process timeout by running the following command:

composer clear-cache
export COMPOSER_PROCESS_TIMEOUT=2000

If you have trouble using the blt alias, verify the BLT Launcher is installed as expected, and restart your terminal session.

If you receive syntax errors from vendor packages, ensure that the version of PHP on your host matches the version of PHP in your VM, or else be sure to always run Composer commands from the VM.

Additional troubleshooting resources¶

If you continue to have issues with BLT, review the following resources:

Troubleshooting¶

Additional troubleshooting resources¶

Acquia Help

Filter by product:

BLT common questions