BLT Hands On Tutorial

Allow about one hour to follow this tutorial and become familiar with BLT. To save time, create the Acquia Cloud Free environment before you start the tutorial.

This tutorial assumes you are on a Mac, but I also wrote a quick start for Drupal and BLT on Windows 10.

Before you begin:
- Create the Acquia free sandbox
- Create the Github repo
- System prerequisites
- Checklist
  - Acquia application ID
  - Acquia app token
  - Github token
  - Drush 9 aliases
  - SSH keys
Create the BLT project
Working with BLT
Edit the composer.json file

Before you begin

Create the Acquia Free sandbox

Log into https://cloud.acquia.com
Click on "Add Application"

- Enter a fun name, such as "kiwifruit", "pepper", or "purple" - When asked to choose a distribution, select the top item, which is **None**

Create the Github repo

Create a new repository at https://github.com/new
Use the same fun name as before (optional)
Do not initialize the repo with a README

System prerequisites

Setting up your host matchine (Mac, Windows, Linux) with PHP and Composer is outside the scope of this tutorial, but here are some general commands to check out your system:

If you type php --version it should indicate PHP 7.2 or better
Consider using Homebrew or on WSL, Linuxbrew to install PHP 7.2 or other dev tools.

brew install [email protected]
brew link php72 --force
source ~/.bash_profile

Type php --ini to identify the path to your loaded configuration file
Type php -m to see which extensions are installed (e.g. php-xml)

ProTip: I recommend installing DrupalVM before you install BLT. The [Quick Start]((https://www.drupalvm.com) guide for DrupalVM provides much more detail then I do here. It only about 10 mins to install DrupalVM using these commands:

cd ~/Sites/
git clone [email protected]:geerlingguy/drupal-vm.git
cd drupal-vm/
vagrant up

Type vagrant global-status to view which VMs are available. Once you've verified that DrupalVM works, go ahead and destroy it with vagrant destory 1a2b3c3f (use your machine ID).

Checklist

Start a text clipping to collect a few API keys and other details you will need in the upcoming steps.

Application ID of your Acquia Free environment (which you can get from the url)
Git repo address for your free environment, e.g. [email protected]:woburn.git
Acquia App Token (with secret key), easily generated at https://cloud.acquia.com/a/profile/tokens
You may need a Github token to push code to your repo from your VM, see https://github.com/settings/tokens
Download the Drush 9 aliases for your Acquia credentials page, as shown:

If you're using old-style Drush 8 aliases, simply running drush acquia-update (see docs) to refresh them. But note that Drush 8 is fading away soon, and Acquia will end-of-life Version 1 of its developer API now that Version 2 is stable.

SSH keys are outside the scope of this tutorial. You need to set up according to these instructions https://cloud.acquia.com/a/profile/ssh-keys. Examples (e.g. ssh [email protected]) and troubleshooting steps are in Acquia Docs.

Create the BLT project

Create a new project as directed in Acquia Docs: https://docs.acquia.com/blt/install/creating-new-project. (I named my project "woburn".)

cd ~/Sites/
composer create-project --no-interaction acquia/blt-project woburn

ProTips:

If Composer fails to install the depedencies, make sure that your corporate VPN is not blocking web traffic. You need a reliable Internet connection that doesn't block access to the open source packages.
If Composer runs out of memory, you forgot to do this:

composer clear-cache
export COMPOSER_PROCESS_TIMEOUT=2000

If BLT doesn't work right away, run the following commands:

./vendor/bin/blt blt:init:shell-alias
source ~/.bash_profile

Push your project to Github. BLT initializes your project directory with a git repo; simply follow Github's instructions to push the coe to Github.

git remote add origin https://github.com/markf3lton/woburn.git
git push -u
git remote -v

You can run blt vm right now to build your VM, but there are a few changes you might as well make right away...

Edit the `composer.json` file

At around line 6, edit the "require": { section. The following changes are appropriate to make:

   "php": ">=7.2",
   "acquia/blt": "^10.2.0",
   "acquia/lightning": "^4.0.0",

Edit the `blt/blt.yml` file

Change the human_name to anything you like, e.g. 'My Dazzling Drupal Site'
Update the git remotes to include your Acquia repo, NOT your Github repo.

git:
  default_branch: master  
    remotes: 
    - [email protected]:woburn.git

For this tutorial, we will use the lightning install profile that is specified in the blt.yml file, or you could change this to demo_umami to use the demo profile included with Drupal core. Note the build.yml file includes all of the available configuration options.

Commit your changes

git add -A
git commit -m "BLT-001: Initialize blt.yml with appropriate project details."

Don't forget to push your commits to your source repo:

git push

Boot the VM

blt vm

When the wizard asks you which "base box" to use, choose ubuntu1604 because that is the version of Ubuntu used by Acquia Cloud at this time.

 Which base box would you like to use? 
  [0] geerlingguy/drupal-vm
  [1] geerlingguy/ubuntu1604

It takes about 10 minutes to provision the virtual machine. At some point you will be prompted to enter your laptop's admin password, which will authorize some changes to your /etc/hosts file.

If everything goes smoothly, you'll get output like this:

==> woburn: Machine 'woburn' has a post `vagrant up` message. This is a message
==> woburn: from the creator of the Vagrantfile, and not from Vagrant itself:
==> woburn: 
==> woburn: Your Drupal VM Vagrant box is ready to use!
==> woburn: * Visit the dashboard for an overview of your site: http://dashboard.local.woburn.com (or http://192.168.152.123)
==> woburn: * You can SSH into your machine with `vagrant ssh`.
==> woburn: * Find out more in the Drupal VM documentation at http://docs.drupalvm.com
[Exec] Done in 07:44

You should now be able to log in to the VM.

vagrant ssh

The output should look like this:


$ vagrant ssh
Welcome to Ubuntu 16.04.4 LTS (GNU/Linux 4.4.0-116-generic x86_64)

 * Documentation:  https://help.ubuntu.com
 * Management:     https://landscape.canonical.com
 * Support:        https://ubuntu.com/advantage
New release '18.04.2 LTS' available.
Run 'do-release-upgrade' to upgrade to it.

Last login: Mon Aug  5 12:30:27 2019 from 10.0.2.2
vagrant@local:/var/www/woburn$ drush @woburn.test ssh
woburn@woburn:/var/www/html/woburn.test/docroot$

Edit your local drush file

Edit docroot/sites/default and change the uri

Change http://local.blted10.com to http://local.woburn.com (use your site name).

Edit the `box/config.yml`

There is a change you should make to your Drupal VM configuration file.

At about line 45 add this:

  # Domain for Adminer
  - servername: "adminer.{{ vagrant_hostname }}"
    documentroot: "{{ adminer_install_dir }}"
    extra_parameters: "{{ apache_vhost_php_fpm_parameters }}"

UPDATE: No longer necessary, this fixed on acquia/blt#3800

Whenever you make any changes to your Drupal VM base box, run this:

vagrant reload --provision

Edit the site aliases

Previously you downloaded your Drush 9 aliases from Acquia Cloud. Add them to you project here:

drush/sites/woburn.site.yml

Under the local directive you should have something like this:

dev:
  root: /var/www/html/woburn.dev/docroot
  ac-site: woburn
  ac-env: dev
  ac-realm: devcloud
  uri: woburnvjylpw8wno.devcloud.acquia-sites.com
  dev.livedev:
    parent: '@woburn.dev'
    root: /mnt/gfs/woburn.dev/livedev/docroot
  host: woburnvjylpw8wno.ssh.devcloud.acquia-sites.com
  user: woburn.dev
  paths:
    drush-script: drush9


# Application 'woburn', environment 'test'.
test:
  root: /var/www/html/woburn.test/docroot
  ac-site: woburn
  ac-env: test
  ac-realm: devcloud
  uri: woburnrxlpde88hl.devcloud.acquia-sites.com
  test.livedev:
    parent: '@woburn.test'
    root: /mnt/gfs/woburn.test/livedev/docroot
  host: woburnrxlpde88hl.ssh.devcloud.acquia-sites.com
  user: woburn.test
  paths:
    drush-script: drush9

Save and commit your changes.

git add -A
git commit -m "BLT-002: Update base box and drush aliases."
git push

Make sure Drush is working

In the above steps, you provisioned a Virtual Machine, re-provisioned it with vagrant reload --provision, and updated several configuration files. You should be able to log in to your VM with vagrant ssh

To start using BLT successfully you should verify that your Drush aliases are working. In general, you should be able to run Drush commands from anywhere but certainly from within your VM.

For example, all of these example commands should work:

drush @woburn.local ssh
drush @woburn.dev ssh
drush @woburn.test ssh

Working with BLT

Now that you have created your new project you can start using BLT.

Install Drupal in your VM

blt setup

Use a BLT recipe to set up Acquia details

vagrant@local:/var/www/woburn$ blt recipes:aliases:init:acquia
To generate an alias for the Acquia Cloud, BLT require's your Acquia Cloud application ID.
See https://docs.acquia.com/acquia-cloud/manage/applications.
 Please enter your Acquia Cloud application ID 92cfd0b6-1111-1111-2222-ee123456b444
Updating /var/www/woburn/blt/blt.yml...
You may generate new API tokens at https://cloud.acquia.com/app/profile/tokens
 Please enter your Acquia cloud API key: <...snip...>
 Please enter your Acquia cloud API secret: <...snip...>
Credentials were written to /home/vagrant/.acquia/cloud_api.conf.
Gathering site info from Acquia Cloud.
Gathering sites list from Acquia Cloud.
Found 1 sites for environment dev, writing aliases...
Found 1 sites for environment test, writing aliases...
Aliases were written, type 'drush sa' to see them.
vagrant@local:/var/www/woburn$

BLT deploy

This command rebuilds your vendor directory and pushes code to Acquia using the deploy script:

blt deploy

Once this completes, go to your Acquia Cloud dashboard and change the code on Dev from master to master-build.

Install Drupal on Acquia Cloud

Now may be good time to install Drupal in your free Cloud environment. From your Acquia Cloud dashboard, click the link under Dev environment (e.g. http://woburnvjylpw8wno.devcloud.acquia-sites.com -- but your site will be different) to run install.php

Be sure to install the "Lightning" profile.

Once this completes, make a database backup on Dev using the Cloud UI.

Update your code locally, and push the updates to your Dev environment on Cloud

Let's add and/or enable some modules...

Working in your project's inside of your VM add a module:

composer require drupal/environment_indicator

Commit the changes, push them to your Github repo. Then run blt deploy again to deploy the new code to your Dev environment.

Promote your newly-updated Dev code to Stage

The next thing to do is move your code and database up to the staging environment. For now, you can do this in the Cloud UI by dragging-and-dropping the database, then the code, from Dev to Stage. This will automatically create a tag and deploy it to Stage.

The Acquia Cloud UI uses "today's date" for auto-tagging, so in upcoming steps we will tag the project at the source. For example, if I tag my work v1.0.0 in git, I want BLT to create a corresponding build tag like this: v1.0.0-build.

Enable modules on stage

Let's consider Stage to be the "production" database at this time. We want to preserve all content and configuration changes that are made on Stage.

Log into Stage with drush @woburn.test uli
Enable the Acquia Connector module
Enable the Environment Indicator module
Go into the Basic site information at admin/config/system/site-information and change the Site name or Slogan
Run drush @woburn.test drush cr

Use BLT to sync you Cloud database to your Local environment

Run

blt sync

Check to confirm the Site name, slogan, and enabled modules are intact on your local environment.

Start working with Configuration Split

From here, follow the tutorial exactly on this page:

https://docs.acquia.com/blt/developer/config-split/

markf3lton/blt-hands-on-tutorial.md

BLT Hands On Tutorial

Contents

Before you begin

Create the Acquia Free sandbox

Create the Github repo

System prerequisites

Checklist

Create the BLT project

Edit the `composer.json` file

Edit the `blt/blt.yml` file

Commit your changes

Boot the VM

Edit your local drush file

Edit the `box/config.yml`

Edit the site aliases

Make sure Drush is working

Working with BLT

Install Drupal in your VM

Use a BLT recipe to set up Acquia details

BLT deploy

Install Drupal on Acquia Cloud

Update your code locally, and push the updates to your Dev environment on Cloud

Promote your newly-updated Dev code to Stage

Enable modules on stage

Use BLT to sync you Cloud database to your Local environment

Start working with Configuration Split

markf3lton/blt-hands-on-tutorial.md

BLT Hands On Tutorial

Contents

Before you begin

Create the Acquia Free sandbox

Create the Github repo

System prerequisites

Checklist

Create the BLT project

Edit the composer.json file

Edit the blt/blt.yml file

Commit your changes

Boot the VM

Edit your local drush file

Edit the box/config.yml

Edit the site aliases

Make sure Drush is working

Working with BLT

Install Drupal in your VM

Use a BLT recipe to set up Acquia details

BLT deploy

Install Drupal on Acquia Cloud

Update your code locally, and push the updates to your Dev environment on Cloud

Promote your newly-updated Dev code to Stage

Enable modules on stage

Use BLT to sync you Cloud database to your Local environment

Start working with Configuration Split

Edit the `composer.json` file

Edit the `blt/blt.yml` file

Edit the `box/config.yml`