Using Lando

This page is out of date and needs reviewing.

Who is this guide for?

This guide is for developers, maintainers and designers looking to use Lando to host an existing site on their computer.

Prerequisites

Once only

The following two steps will only need to be done once per computer you set up Lando on:

  1. You should have already installed Lando. If you haven't yet done that, please head back to the introduction page of these docs and follow the install notes in the How do I install Lando section.

  2. Save a global Lando config file which tells Lando what your username is. This is used for remote drush commands like sql-sync and makes your life easier:

    mkdir ~/.lando; echo "containerGlobalEnv:" > ~/.lando/config.yml; echo -n "  USER: " >> ~/.lando/config.yml; echo $USER >> ~/.lando/config.yml

    Important! If your local user name is different from the user you ssh into servers with then you'll need to manually edit the ~/.lando/config.yml file to add the correct user.

Once per project

The following steps need to be completed each time you want to work on a new/different project but once done you will not have to do them again on the same project:

  1. A clone of the project's files, usually from gitlab.agile.coop, cloned into a directory below your home directory. It doesn't matter where you place it as long as its within your home directory.

    On MacOS a good place to put your projects is under /Users/[your-username]/Sites/

    You should name your cloned site something to distinguish it from others. The default name in gitlab may be sufficient.

  2. Lando must have already be configured and its configuration file (.lando.yml) committed to the repository in the 'git root'.

    How to tell if Lando is already configured on this project?

    There will be a .lando.yml file in the repository root (referred to from here as the gitroot) of the repository. Note that this file starts with a dot so will be invisible unless you list hidden files (ls -la to show a list of files including hidden in the current directory).

    What if there is no .lando.yml file in the gitroot?

    If this is an existing project and has not yet been set up to work with Lando then either follow this set of steps to set it up or ask a developer to help. If you are starting a new project then a developer should follow these steps to get you up and working.

  3. Create a .env file in the git root (not the web root) by following the next steps. The .env does not get committed to the repository and is specific to your computer. This allows you to have different configuration from others if needed.

    Git root? The git root or gitroot is the respository root, the place where the hidden .git directory exists.

    1. Copy and paste this command whilst in the git root (note - only tested on Linux):

      echo -n "DRUSH_OPTIONS_URI=" > .env; lando info | awk '/https/ {a=$1} END{print a}' | sed -n -E 's/\'https(.+)\/\'/http\1/p' >> .env; echo "DRUSH_OPTIONS_ROOT=/app/web" >> .env

    2. Double check the command worked. Edit the .env file and make sure it looks something like this (the domain will be different):

      DRUSH_OPTIONS_URI=http://projectname.lndo.site
DRUSH_OPTIONS_ROOT=/app/web

      If the domain doesn't look right in your .env file just run lando info and copy paste the correct domain under the appserver (at the top of the output) urls key. Usually this is the third entry in the list and will always end with .lndo.site

How to start Lando on this project

Now you have completed the steps above (you'll only need to do those steps once per project) you can fire up Lando.

It is best to start Lando while in the git root. This is because Lando will pick up an .env file if it exists which will inform Drush of some useful options.

To start Lando run the following:

lando start

Once it finishes you will see something like the following output:

BOOMSHAKALAKA!!!

Your app has started up correctly.
Here are some vitals:

 NAME            projectname
 LOCATION        /Users/tanc/Sites/projectname
 SERVICES        appserver, database, mailhog, node
 APPSERVER URLS  https://localhost:32822
                 http://localhost:32823
                 http://projectname.lndo.site
                 https://projectname.lndo.site
 MAILHOG URLS    http://localhost:32819
                 http://mailhog.projectname.lndo.site
                 https://mailhog.projectname.lndo.site

It may take some time for Lando to completely bring up your environment the first time you run it as it needs to pull some large images off the web and store them locally. These images represent the containers Lando is using to run a webserver, nodejs etc. There will also be a couple of build steps run the first time the container is created, this will include downloading and installing drush launcher within the appserver container.

Configure Drupal

Now we should have a functioning web server but Drupal doesn't yet have a database or the settings to know where to find MySQL. Depending on whether this is a Drupal 8+ site or a Drupal 7 site the instructions are slightly different.

Drupal 9

  1. Add an htaccess file, run this from the git root:
curl -o web/.htaccess https://raw.githubusercontent.com/drupal/drupal/9.3.x/.htaccess

  1. Import the database with one of the two following methods:

    • Clone the production (or stage) database using drush:
    lando drush sql-sync @remote.prod @self

    If you tried the drush command and it failed, its possible the drush aliases haven't been set up for this project yet. You can ask a developer to help set these up as each Drupal 9 project should have them. Its also possible you may have skipped step 2 in the 'Once only' section as your username is needed for the container to be able to ssh to the server.

    • Obtain a copy of the production database and place it in your git root, then import the database with something like the following (changing the sql file name to the one you have downloaded):
    lando db-import mydatabase.sql

Drupal 7

  1. Add the settings.php file with the Lando credentials already configured. This command should be run from the git root (not the web root):
curl -o web/sites/default/settings.php https://gitlab.agile.coop/agile-public/lando/raw/master/d7/settings.php
  1. Add an htaccess file, run this from the git root:
curl -o web/.htaccess https://raw.githubusercontent.com/drupal/drupal/7.x/.htaccess
  1. Obtain a copy of the production database and place it in your git root, then import the database with something like the following (changing the sql file name to the one you have downloaded):
lando db-import mydatabase.sql

Wordpress

  1. Add the wp-config.php file with the Lando credentials already configured. This command should be run from the git root (not the web root).
curl -o web/wp-config.php https://gitlab.agile.coop/agile-public/lando/raw/master/wp/wp-config.php
  1. Add a .htaccess file for the WordPress site
curl -o web/.htaccess https://gitlab.agile.coop/agile-public/lando/raw/master/wp/htaccess

  1. Get the database for the site, the best ways to do this is to use the Migrate DB plugin found at /wp-admin/tools.php?page=wp-migrate-db (a Lando export profile should be setup, if not, copy the one setup for Green Accountancy). Importing the database directly from a dump is not going to work as WordPress includes absolute URLs in the database that need to be rewritten.

  2. Import the database with something like

lando db-import mydatabase.sql.gz
  1. You may need to edit the $table_prefix variable in the web\wp-config.php for the site. The calue for this can be found in the .site.yml file in the gitroot.

View and use your web site

Finally! The part you've been waiting for...

To view your web site you should stick the domain name in the address bar of your browser. "How do I know the domain name?" I hear you weep. Remember the output in your terminal where it said "BOOMSHAKALAKA!!!"? Of course you do. Beneath that output you should see the domain name for the appserver, something like http://projectname.lndo.site

How to stop using Lando on this project

To stop the containers you can run the following from the gitroot of the project you want to stop:

lando stop

You can run multiple projects at once as Lando will avoid port clashes by randomising external ports on your host machine. It is probably wise to get in the habit of stopping a project before working on a new one to keep your system resources in check.

How to close Lando down completely (free up port 80)

As Lando runs a server on port 80 which it uses to proxy requests back to the various containers you may find you need to completely shut down Lando so you can work on another dev environment that uses port 80. To do this you issue the poweroff command:

lando poweroff

You can also stop/quit the Docker app (MacOS users will notice it in the menu bar at the top of the screen). This is safe to do and will close down all active sites. When you next open Docker (MacOS users will note it is an application in /Applications) you will need to fire up your project again with lando start

How to import a database

To manually import a database (not sync it with drush) you will need to temporarily place it within your project directory (so that it is available within the containers) and run the following command:

lando db-import mydatabase.sql

You should delete (or move out of the project) the sql file after the import completes.

See full documentation here.

How to use drush commands

You can issue drush commands as you usually would but prefix them with lando first. For example, to rebuild caches:

lando drush cr

More advanced drush usage using aliases can be found in this part of the documentation.

Theming

All the front end tooling you need should be included in the nodejs container, started and configured when you bring Lando up on this project. You can then run the usual commands by prefixing them with Lando first, for example:

lando npm start

More details can be found in the theming section of these docs.

Troubleshooting

If you get stuck ask a developer. If you are a developer or want to fix it yourself then please take a look at the troubleshooting section.

Last updated: