Acquia BLT Lando integration

This is an Acquia BLT plugin providing Lando integration.

This plugin is community-created and community-supported. Acquia does not provide any direct support for this software or provide any warranty as to its stability.

OS Support

While Lando itself can be used with any operating system (see their system requirements here) this plugin has been built with a Mac OS host in mind. See my blog for details on setting up a Macbook for work as a host machine.

This project can be used on non-Windows hosts, but you will have to remove the ssh-fix tooling and the related ssh code (as it it specific to Mac OS).

Installation and usage

To use this plugin, you must already have a Drupal project using BLT 11 (or higher).

1. Add this plugin to your project using composer:

If using composer 2: composer require --dev mikemadison13/blt-lando -W

If using composer 1: (I strongly recommend you update to composer 2) composer require --dev mikemadison13/blt-lando --with-all-dependencies

Note: if you are using drupal/recommended-project (or another project template) that sets the minimum-stability to "stable" you may have trouble installing this plugin. You can either change your stability to "dev" or more specifically composer require like:

composer require mikemadison13/blt-lando:dev-main -W

2. Ensure that your blt/blt.yml file has properly set the project.machine_name key (as this will be used during template generation by this plugin).

3. Initialize the Lando integration by calling blt recipes:vm:lando, which is provided by this plugin.

This will copy a template version of the .lando.yml to your project root directory and instantiate a number of other BLT and Drupal settings files required to make Drupal bootstrap properly in a Lando container. Make sure to commit these files (where appropriate, remember that BLT gitignores local settings and local blt files by default, and these "local" specific files should not be committed) as well as your updated composer.json to Git.

Note: the template YAML file assumes standard BLT steps for builds and is based upon the acquia image. The plugin will attempt to customize the file based on your project's machine and host names as defined in your blt.yml file.

4. Carefully review the created .lando.yml file prior to running lando start

5. Once Lando has been provisioned, run lando blt setup to install Drupal via BLT.

Note: To run the behat command, it now requires the behat plugin (acquia/blt-behat) to be added manually.

Constraining Composer

Now that composer 2 is out, Lando should default to composer 2. HOWEVER if you are running much older versions of Drupal, you may still need composer 1. You can add this into your project manually with the following config key:

config:
  composer_version: '1.10.22'

Configuring for Multisite

Configuring a local environment for multisite requires both a change to your .lando file (and rebuilding) AND configuration of your Drupal application via sites.php and the sites directory.

The following assumes that your first / default / initial site will use the "default" folder in Drupal, and the default database server that comes provisioned with the recipe.

Additional sites require two changes each in the .lando.yml.

Adding Appserver Proxy URLs

If you are setting up a domain-based multisite approach, you should provide a new proxy for each site in your multisite setup. If you are using path-based multisites this step isn't necessary.

proxy:
  appserver:
    - zero.lndo.site
    - first.lndo.site
    - second.lndo.site
    - third.lndo.site

The proxy config should be a separate section in the .lando.yml file. Note that your default site does need an entry here.

Adding Databases

Each site beyond the default will need additional service entries for databases.

services:
  first:
    type: mysql:5.7
    portforward: true
    creds:
      user: acquia
      password: acquia
      database: first
    second:
      type: mysql:5.7
      portforward: true
      creds:
        user: acquia
        password: acquia
        database: second
    third:
      type: mysql:5.7
      portforward: true
      creds:
        user: acquia
        password: acquia
        database: third

Make sure to set the database credentials in each site's settings file to match. The db host will be the service name (e.g. first).

Adding Solr

Configuring a Lando Solr Service

The .lando.yml file included with this plugin does not include an Apache Solr service by default because not all projects need Solr!

However, if you wish to use Solr, simply add an additional service to the .lando.yml file like the following:

services:
  solr:
    type: solr:7.7
    core: drupal
    portforward: true
    config:
      dir: .lando/solr

The config directory's contents can be downloaded from the Acquia Cloud after configuring solr there (look for a 'download configset' link).

Then rebuild your VM using lando rebuild.

I've used this blog in the past as a reference and it's terrific.

Configuring Drupal

Note that for Search API you'll need the following information for a local server:

Connector: standard
scheme: http
host: solr
port: 8983
path: /
core: drupal

notes:

• the core is configurable so if you want it to be something else, change the core definition in the service definition and update the solr config to be the same!
• the internal / localhost connectivity for the server is NOT the same as the service url that lando will report (and that's ok)
• even though Search API ships a config file, I have not been able to get the solr service to recognize and pull the config file from the appserver (so there is not currently a config path here)

Local Overrides

Once you have the local server defined, put the configuration in your local config split.

You also need to manipulate your search indexes so that they will utilize the local server on your local. This can be done with a $config override in a local settings file like:

$config['search_api.server.acquia_search_solr_search_api_solr_server']['status'] = false;
$config['search_api.index.acquia_search_index']['server'] = 'local';
$config['search_api.index.acquia_search_index']['status'] = true;
$config['search_api.index.acquia_search_index']['read_only'] = false;

This config override will:

• disable the Cloud based Acquia server
• change the index to the local server
• ensure the index is enabled (as it may become disabled locally when the Acquia server is unreachable)
• ensure the index isn't read only (as it may become read only when the Acquia server is unreachable)

You will need to repeat the 2nd - 4th lines of this example for each index in your codebase.

Debugging with XDebug

Between the recipe for Lando and this config file, XDebug is largely pre-configured. However, in the .lando.yml the appserver's xdebug key must be changed from false to true and then the container must be rebuilt. Once enabled, you can toggle XDebug on when you want to use it, which I have provided simple tooling for:

lando xdebug-on
lando xdebug-off

However, simply turning on XDebug isn't enough, as you'll still have to manually configure PHPStorm for each project. At a high level, this is broken down into three steps:

1. Add a server in PHPStorm (or other IDE). The plugin assu,es you will same this 'appserver'
2. Add a PHP Web Page debug config (using the server)
3. Instruct both the IDE and your browser to start debugging / listening

Here's an article on configuring PHPStorm. Note that the recipe comes pre-configured to debug in PHPStorm. Other IDEs will require some additional tweaks.

Finally, it is possible despite fully configuring that XDebug is still not functioning. This article walks through additional steps that will ensure that PHPStorm detects that the PHP version running inside the container has XDebug.

Warning:

Once configured for XDebug and PHPStorm, your project may begin hanging on Drush or other php terminal-based commands. IF so, confirm that you haven't tripped the debugger in the IDE!

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.