Setting up a new project using BLT, Dev Desktop, and Lightning

Posted by Jeff Beeman on Sat, 05/12/2018 - 17:43

This is the first in a series of posts where I'll capture how I built a new Drupal 8 version of using BLT, Dev Desktop, and Lightning. In later posts, I’ll talk about other local development solutions, dependency management, content migration, and how BLT helps me build and deploy artifacts to Acquia Cloud.

I chose BLT because it addresses a host of tasks related to the development workflow I want to have for my site. It's Composer-driven and centered around building and deploying artifacts. I chose Lightning because it packages up a selection of Drupal site building tools I knew I'd want to have in my site. In particular, I wanted Lightning's media management and publishing workflow.


If you’re following along, you’ll need Dev Desktop, Git, and Composer. Fortunately, I had all these things installed and ready to go (be sure to start up Dev Desktop after installing it).

Other dependencies you’ll need are documented by BLT. If you’re on OS X, I recommend using Homebrew to install what you’ll need:

brew install php71 git composer;
composer global require "hirak/prestissimo:^0.3”;

Note: If you read the BLT docs, you will not need Drupal VM or Cog dependencies for what you're doing here. I may get to Behat much later, but don’t worry about those dependencies for now.

Create the project

BLT’s documentation for creating new projects is excellent. If you’re starting a new project, or if you’d like more details on each of these steps, I recommend checking it out.

Keeping with the naming theme I used throughout my rebuild, let’s call the new project Exodar (hopefully some of you will get the reference).

composer create-project --no-interaction acquia/blt-project exodar

Configure BLT

Once the project is created, you need to update blt/blt.yml with configuration for the project. Note that the file has many settings in it. The snippet below only includes lines relevant for initial setup of the project with Dev Desktop. Keep the rest of the default settings in your own file if you’re following along.

  machine_name: exodar
  prefix: EX
  human_name: 'Exodar'
    name: lightning
    protocol: http
    hostname: 'exodar.dd'
    port: ‘8083'

The settings above tell BLT that the project’s name is Exodar and the local site URL is http://exodar.dd:8083/

Configure local Drush options

Edit docroot/sites/default/local.drush.yml and set the URI to your local site URL:

  uri: 'http://exodar.dd:8083'

Add the new code base as a local site in Dev Desktop

Over in Dev Desktop, add a new site via the “Import local Drupal site…” option. You’ll need to select the docroot subfolder, and then change the “Local site name” value accordingly so that Dev Desktop doesn’t call it “docroot” for you. Finally, be sure to use PHP 7.1+.

Configuration dialog for the Exodar project in Dev Desktop

Run BLT’s setup process

blt setup

Run BLT setup task to execute the full initial setup process to build your code base. You’ll be asked if you want to drop your database tables. Say “yes” - it’s safe. You don’t have a site yet!


You now have a fully built code base and Drupal has been installed. From your project’s directory, use Drush to login:

drush -l http://exodar.dd:8083/ uli

Wrapping up

You now have the project built and usable inside of Dev Desktop! You can start doing any number of site building tasks in this new site, and I’ll cover more topics in follow-up posts:

  • Further tuning the local environment: I’ll cover a couple basic things around Drush, Composer, editor configuration, pushing my work out to Github, etc.
  • Module and configuration management lifecycle: Adding new modules and managing their configuration.
  • Creating a sub-profile: I like to manage my site as a sub-profile of Lightning, which allows me to override dependencies, add my own requirements, and continually test the process of rebuilding my site.
  • Deploying to Acquia Cloud: Connecting Dev Desktop to Acquia Cloud, as you would with “normal” a code base won’t work as expected at this point. Because you're in a BLT-based project, you’ll be using BLT to run the build and deployment process.