Dockerize Drupal with Lando

If you haven’t heard of Docker yet, it’s time you did some research. Basically, Docker can be used to establish and create a standard environment in which your website can be run. This prevents situations where the same code works on your laptop but doesn’t work on the server or someone else’s computer.

Lando vastly simplifies local development and DevOps so you can focus on what’s important; delivering value to your clients and customers.

In this article, you’ll learn how to use Lando to easily dockerize your Drupal site without having to dig deep into the core concepts of Docker. You will also read about using Lando for complex projects that need additional services and customizations.

Two Minute Version

• Install Lando as per documentation.
• In your Drupal project root, run lando init and complete the process.
• Configuration should be generated in a .lando.yml file.
  • Fine-tune this Landofile as per requirements.
• Run lando in your terminal to see a list of available commands.
• Run lando start to kick-off your project.
  • Your site should be available at PROJECT-NAME.lndo.site.
• Run drush commands like lando drush --version.
• When you’re done working run lando stop to stop the containers.

Getting started

Here are some things you need in order to get started.

• Install Lando by referring to Lando docs.
  • Don’t worry if you don’t already have Docker installed because the Lando installer comes with Docker.
• Create a Drupal project first or choose an existing project.
  • This article assumes that you’re using Drupal 8.
  • However, not much should change if you’re using a different version.
• You’ll need some basic command-line skills as well.

Though this article is specifically about using Lando with Drupal, making it work with other PHP applications should not be very difficult.

Configuring Lando

Make sure Lando is installed properly by running lando version in a terminal. You should see the version of Lando you’re running.

$ lando version
v3.0.0-rrc.1

Once Lando is installed, do the following steps:

1. In your terminal window and cd into the root of your Drupal project.  This can be one of the 2 directories below:
   • Drupal’s docroot, i.e. the directory containing index.php.
   • The directory above Drupal’s docroot – this is more common.
2. If you’re using Git, I'd suggest making a commit at this point.
3. To configure Lando, run the command lando init. This will ask you a series of questions about your project which you should answer correctly.

# Location: /users/jigarius/Sites/example.com
$ lando init

# In the root of the project's code base.
? From where should we get your app's codebase? current working directory

# The framework you're using, e.g. drupal8 / drupal9.
? What recipe do you want to use? drupal8

# The directory containing index.php.
? Where is your webroot relative to the init destination? web

# A project name.
? What do you want to call this app? lando-drupal-example

Doing this will generate a .lando.yml file, aka Landofile, containing Lando configuration. You can fine-tune this config file as needed.

Hostnames

By default Lando makes your site available at PROJECT-NAME.lndo.site. Lando’s docs suggest that it is possible to configure additional/custom hostnames (proxies), however, it is recommended not to do this unless absolutely necessary.

# Makes the site available at dev.example.com
proxy:
  appserver:
    - dev.example.com

Personally, I found the proxy behavior to be random and couldn’t get them to work except on some projects.

Configuring Drupal

During the configuration process, Lando sets up some Docker containers for your application:

1. appserver: this contains the web server (e.g. nginx or apache) and your application’s code.
2. database: this contains your database server, usually MySQL.

For your local Drupal site to detect and use the Lando’s database server and services, you need to make some changes to your site’s $settings. You can put Lando settings in a settings.lando.php as follows.

<?php

// Prepare a LANDO_INFO constant.
define('LANDO_INFO', json_decode($_ENV['LANDO_INFO'], TRUE));

// When using lando, use Lando settings.
if (defined('LANDO_INFO')) {
  // Databases.
  $databases['default']['default'] = [
    // Since "mariadb" drivers are the same as "mysql", we hard-code "mysql".
    'driver' => 'mysql',
    'database' => LANDO_INFO['database']['creds']['database'],
    'username' => LANDO_INFO['database']['creds']['user'],
    'password' => LANDO_INFO['database']['creds']['password'],
    'host' => LANDO_INFO['database']['internal_connection']['host'],
    'port' => LANDO_INFO['database']['internal_connection']['port'],
    'prefix' => '',
    'collation' => 'utf8mb4_general_ci',
  ];
  var_dump($databases);
}

// Trusted host patterns.
$settings['trusted_host_patterns'][] = '^.*\.lndo\.site$';

 A more complete version of the settings.lando.php can be found in the sample code for this article on GitHub.

You can now include these settings into your Drupal app from your settings.php or settings.local.php file as follows.

// Include settings for Lando services.
if (file_exists(__DIR__ . '/settings.lando.php')) {
  include __DIR__ . '/settings.lando.php';
}

This tells your Drupal site to use Lando’s database server to store data. If you’re using additional services like Solr, you might need to add some more lines to the settings.lando.php file to configure those services.

Common commands

Here are some commonly used Lando commands. These commands need to be executed from within a project for which you’ve configured Lando.

• lando: displays a list of all commands with help text.
• lando init: starts a wizard for configuring a new project.
• lando info: displays information about services.
• lando start: starts project containers.
• lando stop: stops project containers.
• lando restart: restarts project containers.
• lando rebuild: rebuilds project containers.
• lando destroy: delete project containers and data.
• lando ssh: SSH into a service. Defaults to the web service.
• lando drush: executes a drush command.
• lando drupal: executes a drupal console command.
• lando mysql: launches a MySQL shell on the database service.
• lando php: executes a PHP command.
• lando composer: executes a composer command.

For any command, you can add the --help flag for detailed information.

Using drush

There is no special configuration required to make Drush work with Lando. Just cd into your project’s root, i.e. where the .lando.yml file lives, and run commands like:

lando drush --version

However, for Drush to know the URL of your local website, you can add the following lines to your  drush.local.yml file.

# File: sites/default/drush.local.yml
options:
  uri: "http://example.lndo.site/"

You will also need to make sure that the above drush config file is actually picked up by Drush. You can do this as follows:

# File: drush/drush.yml
drush:
  paths:
    config:
      - "web/sites/default/drush.local.yml"

This makes commands like drush uli use the correct URL for your dev website.

Customizing builds

In the .lando.yml file there exists a special key named services which allows you to add specific instructions for services in your project. To customize any of your service containers, you must create a key for that service under the services key and add your instructions there.

Let's say you want to run composer install when your Drupal project’s containers are being built. You can do this by simply adding the following lines to your .lando.yml:

services:
  appserver:
    build:
      - composer install

It is also possible to use a custom Dockerfile and to customize environment variables as well. However, those topics are outside the scope of this article. You can read more about it under the services section in the Lando documentation.

Additional services

Lando offers a number of additional services that you can integrate into your project.  You can read more about Lando services in the Lando documentation. This usually involves adding some lines under the services key of the .lando.yml file.

As an example, here’s how you would add a mailhog service to your project.

# File: .lando.yml
# ...
services:
  mailhog:
    type: mailhog
    portforward: true
    hogfrom:
      - appserver

After making the changes, running lando restart, should finalize the setup. Lando will also show you a URL at which Mailhog will be available.

Conclusion

Lando lets you dockerize your projects with ease and its usage is not limited to Drupal (or PHP). It is easy to get started with Lando and their docs are very informative. Also, Lando reveals parts of Docker and docker-compose APIs which makes it easy to customize your builds if you have Docker knowledge.

Personally, I’ve had certain problems with my Lando setup which get annoying at times and call for a lando rebuild once in a while. The problem that I face the most is that the code inside the appserver container goes out of sync with the code in the host. Also, certain parts of their documentation are not up-to-date/clear and you might have to create a support ticket to get some answers. You can always submit PRs to update the documentation for extra points 😉

Next steps

• See the sample code for using Drupal with Lando.
• Read Lando documentation.
• Read Docker documentation.
• Read Docker Compose documentation.