You Don’t Need BLT on Acquia Cloud

Goal

Learn how to remove BLT from a Drupal 10 site hosted on Acquia Cloud

Overview

Acquia BLT was created almost a decade ago as a veritable Swiss Army Knife to fill feature gaps in the Drupal ecosystem. Since then, tools such as Composer, Drush, and Drupal itself have evolved to provide similar or even better features, and for many sites BLT may be overkill.

This tutorial will help you remove BLT from a Drupal 10 application and show you how to adapt your workflow to fulfill the same use cases with other open-source tools.

Remove core BLT packages

• Ensure your site is ready for the migration

  • Ensure your site is running the latest versions of all Composer packages. Especially, ensure you are using the latest release of BLT (currently 13.7.4).
  • Ensure your default.local.settings.php (in docroot/sites/default/settings) is up to date and mode 755.
  • Ensure your site is running normally in your local and cloud environments.

• Replace BLT settings with Drupal Recommended Settings

  Remove the blt.settings.php include from your settings.php. You can replace this with the Drupal Recommended Settings plugin, which provides all of the same settings functionality as BLT, including (but not limited to):

  • Caching
  • Configuration management (including Config Split)
  • Continuous integration
  • Logging
  • Public and private filesystem management
  copy

   composer require acquia/drupal-recommended-settings:^1.0.1

  Update default.local.settings.php and local.settings.php to use the Environment Detector provided by Drupal Recommended Settings instead of BLT:

  use Acquia\Drupal\RecommendedSettings\Helpers\EnvironmentDetector

• Remove BLT files

  Remove the BLT directory in your repo root: rm -rf blt

  Note that this does not purge all traces of BLT from your codebase. You may find references to BLT in the following files:

  • .gitignore
  • composer.json (autoload and scripts sections)

  However, we recommend you ensure your site is stable before doing any final cleanup.

• Set up GrumPHP

  BLT validates any changed code when you commit changes to your project. Third-party tools such as GrumPHP can do the same thing with more features and flexibility than BLT. Run the following command and review suggested plugins for safety and trust them when prompted.

  composer require --dev phpro/grumphp php-parallel-lint/php-parallel-lint

  To mimic the existing BLT pre-commit validation, do not accept the offer to create a grumphp.yml file. Instead, use this one:

  copy

   grumphp: tasks: { composer: null, phplint: null, yamllint: null }

• Remove BLT, add Drush

  copy

   composer remove acquia/bltcomposer require drush/drush

• Replace BLT commands with Composer scripts

  Replace BLT commands such as setup and validate with Composer equivalents by adding the following to the composer.json scripts section:

  copy

   { "drupal:install": "drush si minimal --existing-config", "drupal:test": "phpunit", "drupal:validate": "grumphp run"}

  Now instead of running blt setup, blt validate, and blt test, you can run composer drupal:install, composer drupal:validate, and composer drupal:test, respectively.

  You may need to make changes to these scripts based on your site configuration and test structure. For instance, tests may be run using Behat instead of PHPUnit, or you may need to install Drupal and import config as separate steps:

  copy

   drush si drush config:set system.site uuid drush cim

  Instead of explicitly setting UUID, you could also use a Drush hook or the Config Sync without Site UUID module.

Congratulations! You’ve removed the core of BLT from your site. Ensure that it’s still running normally locally and that you can run the new Composer commands you just defined. If so, commit your changes (unless you are using Acquia Pipelines to deploy code; see the next section in that case.)

If you run into trouble, Acquia provides the Drupal Canary Project as a reference implementation of Drupal 10 without BLT, which you can refer to for help with your own application.

Continue reading to migrate specific additional features.

Remove BLT from Pipelines

BLT provides out-of-the-box Acquia Pipelines integration via acquia-pipelines.yml. Modify this file to remove references to BLT.

• Update acquia-pipelines.yaml

  • Remove the BLT_DIR environment variable.
  • Replace call to setup_env script with: mysql -u root -proot -e "CREATE DATABASE IF NOT EXISTS drupal"
  • Replace call to validate script with: composer drupal:validate
  • Replace call to setup-app with: composer drupal:install
  • Replace call to tests with: composer drupal:test
  • Replace artifact build step with the following:
  copy

• Verify changes

  Commit and push these changes to your repository. Verify that Pipelines builds, tests, and deploys your site as expected.

  If assets such as frontend libraries are present in your source repository but missing from the build artifact, make sure they are properly defined as scaffold or vendor files in composer.json:

  "docroot/themes/custom/{$name}": [

  "type:drupal-custom-theme"

  ],

  This is necessary since ACLI deploys artifacts slightly differently than BLT. Whereas BLT used a hardcoded list of files to forcibly git add (the so-called "deploy gitignore file"), ACLI dynamically determines these files by checking for scaffold and vendor files defined in composer.json.

Remove BLT from Code Studio

No specific work is required to support Code Studio. If Code Studio AutoDevops builds were passing prior to the migration, they should continue working as before.

Remove/replace Cloud Hooks

If your application is hosted on Acquia Cloud Next, consider using Cloud Actions on Acquia Cloud Next as an out-of-the-box replacement for Cloud Hooks. In this case, simply enable Cloud Actions and remove Cloud Hooks from your application:

 rm -rf hooks

Applications still on Acquia Cloud Classic will need to replace BLT's Cloud Hooks with individual Drush commands to replicate the functionality of BLT. To do this, remove all of the shell scripts from the hooks directory in your application. Instead, create a script such as the following at hooks/common/common.sh:

 #!/bin/bashset -evdrush updbdrush config:set system.site uuid 7139fc96-2b92-48c5-8e8a-cb79472aa19fdrush cimdrush crset +v

Then run the following commands to link this common script into each hook event directory:

 ln -s ../common.sh hooks/common/post-code-deploy/common.shln -s ../common.sh hooks/common/post-code-update/common.shln -s ../common.sh hooks/common/post-db-copy/common.sh

Remove/replace other BLT integrations

The following features have their own migration path:

• ACSF and Multisite – The Drupal Recommended Settings plugin facilitates the settings capabilities of BLT for multisite.
• SAML – Acquia largely recommends utilizing the SAML Auth module today. Most of our prior work around the “dedicated” SAML capabilities in BLT (and later the BLT SAML Plugin) were related to the complexities surrounding the SimpleSAMLPHPAuth module and PHP library. SAML Auth is much simpler to setup and configure (entirely via Drupal configuration).
• BLT plugins (such as Behat tests) – We recommend exploring composer-based automation for commands contained in BLT plugins (e.g. composer test that will execute the necessary commands for tasks such as automated testing).
• Twig linting – GrumPHP Can also be configured to lint Twig.