Migrating to BLT - Part 1

Photo CC-BY by amagill

While I’m a fan of CI/CD automation it took me a while to reinvent a few wheels until I realized that Acquia’s BLT for Drupal 8 is the template that I want. In the next few posts I will provide you some tips and tricks, for the things which aren’t self-explanatory, yet.

Prerequisites

Make sure you read over the BLT documentation once fully to understand certain general concepts. For example, it’s imperative to understand that the project repository is not what gets deployed but rather a deployment artifact is pushed to a separate repository that also includes the blt tools but no development dependencies.

Migrating an existing project

The documentation recommends starting with a fresh site but I find it much easier to see the differences in setups when I have a working real-life site to do the comparison on. The documentation says it’s possible to add BLT to an existing project but I find it unhelpful for beginners to figure out if the migration actually was complete and ideal, or not. Plus, you likely have idiosyncrasies in your setup. Here’s how you can get there (based on v8.8.3) through manual merging.:

1. Create a new site with BLT. Follow all steps including setting up the VM and blt local:setup.
   1. Don’t forget to set the installation profile to what you had before in project.yml.
   2. Remember to customize the vagrant_ip (and of course set php_version to "70").
   3. Don’t try moving the site to a subdirectory of the repo, weird stuff happens with Vagrant and other scripts.
2. Delete the git directory that was created for you and move your existing git folder over. You can now add items selectively and git add them until you have everything. A good start would be your “custom” folders and the require entries in composer.json, minus core et al. At the end your staged changes should mostly show renames.
3. Add a useful target to the site aliases to sync from and set it in project.yml. For example, to sync directly from production set remote under drush.aliases to '${project.machine_name}.prod' and execute blt local:refresh afterwards.
   1. BLT is actually smart enough that it can reset your site uuid and install from the config directory from scratch but you’re going to need relevant data anyway, so why not fetch it now.
   2. The refresh will sanitize user accounts, so you might want to use drush upwd or drush uli afterwards.
4. You have essentially removed the installed site now but left all supporting files intact and it’s now easy to move over the yml configuration into config/default and you can locally cim & cex or use blt commands afterwards.
   1. Note that the site hash is in /salt.txt and needs to be updated, too, from the existing site.
5. Done! Your site should now be locally available with everything you had before but under BLT.

Commands to try out

I’m far from an expert yet but just the pure joy of use of everyday usage is really worth the effort. For example:

• blt local:refresh Already mentioned above, it syncs your environment from a remote destination and does all the stuff you might forget to do. It can also fetch the site files, or do that directly with blt sync:files. To think I used to write drush sql-sync commands by hand…
• blt local:update Clearly a lot nicer than chaining drush commands, e.g.: drush cim -y && drush updb -y && drush cr -y
• blt fix Just run all the fixes. No weird issues with the phpcs config path, if not installed globally, or having to manually specify paths. It just works. 🙌
• blt deploy Details on that in a later post but one of the key features of BLT which really improves on simpler scripts, which most of us use to just automate copying files and calling composer. I’m extremely satisfied with the output of this command and the abstraction it provides.

In a few days I’ll post more about how to work with config_split and the relevant deployment commands, when you are not using Travis/Acquia Cloud.