Setting up Lando for an existing project

This page is out of date and needs reviewing.

Who is this guide for?

These steps are relatively complicated (although easier when you've done it once). Therefore we suggest only developers undertake the steps for setting up existing projects.

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.

Understanding these steps

Don't just copy paste each of the commands! You will need to edit some lines before hitting return. You will also need to open an editor (vim, nano etc) to modify lines in files.

Project naming convention

The specified convention [client code][project code] is the recommended naming scheme for new projects. The client code should be four letters (or less but ideally four), as should the project code. If the project is the organisation's main site then main should be used for the project code. Otherwise a code representing the project should be used.

Examples:

Setting up an existing project

To set up an existing project which doesn't have a .lando.yml file in the git root, the following steps can be used for Drupal 8+ or Drupal 7 sites

Drupal 8+

  1. Starting somewhere within your home directory, clone the project's repository from the Agile Collective GitLab server and change the word projectname in the following command so that it follows the convention [client code][project code]:
git clone git@gitlab.agile.coop:client/project.git projectname
cd projectname
  1. Copy the boilerplate Drupal 8+ Lando config and paste into a .lando.yml file in the gitroot directory.
curl -o .lando.yml https://gitlab.agile.coop/agile-public/lando/raw/master/d8/.lando.yml

  1. Edit the .lando.yml file and change the value for the name key so that it follows the convention [client code][project code].

    Also change the domain name for mailhog under the proxy key. The mail.projectname.lndo.site domain name should be updated so that projectname is something unique to the project, using the name value is preferable.

Note that Lando will remove any non alpha characters from domain names so if you wrote agile-collective for the project name the domain name will be agilecollective.lndo.site. You can confirm the domain name with lando info.

  1. (Optional) Modify the .lando.yml file for this project's particular needs. For example, it may need a specific PHP version, or Solr. See the Lando docs for details on how to add services.

Note that the front end stack might require specific Lando configuration. This is touched on in the Front end tooling set up

  1. Configure the domain for drush and Lando by creating a .env file with the following content (edit the domain to suit your project, can be discovered with lando info). You should replace projectname with whatever you chose for the .lando.yml file:
echo "DRUSH_OPTIONS_URI=http://projectname.lndo.site" >> .env
  1. Add the web root as a environment variable so that drush commands can be run from outside the webroot.
echo "DRUSH_OPTIONS_ROOT=/app/web" >> .env
  1. Bring the Lando containers up:
lando start
  1. Download the boilerplate settings.local.php file (run this from the git root):
curl -o web/sites/default/settings.local.php https://gitlab.agile.coop/agile-public/lando/raw/master/d8/settings.local.php
  1. Create the drush aliases:
mkdir -p drush/sites
curl -o drush/sites/remote.site.yml https://gitlab.agile.coop/agile-public/lando/raw/master/d8/remote.site.yml
curl -o drush/sites/server.site.yml https://gitlab.agile.coop/agile-public/lando/raw/master/d8/server.site.yml
  1. Edit the two drush alias files and enter the correct details for the remote server. More detailed information about the contents of these files and the set up of aliases can be found in the drush alias set up document.
  2. Import the database. This can be done with one of the following two methods:
  1. Add an .htaccess file (run this from the git root):
curl -o web/.htaccess https://raw.githubusercontent.com/drupal/drupal/8.6.x/.htaccess
  1. Modify the .gitignore file to ignore the .env file:
# Ignore .env files as they are personal
/.env

# Ignore most sql file variations
*.sql
*.sql.gz
*.sql.tgz
*.mysql
  1. Access your site:
lando drush uli
  1. Commit the .lando.yml file, the drush aliases and the .gitignore file to the repository (run this from the git root):
git add .lando.yml .gitignore drush
git commit -m "Adds .lando.yml file, drush aliases and updates gitignore"
git push origin master
git checkout develop
git merge master
git push origin develop
git checkout master
  1. Note the project shortname in the support master sheet.
  2. Go to the front end set up documentation and configure the theme to work with Lando. Commit any changes.

Drupal 7

  1. Start in the repository root (referred to from here as the git root) directory:
cd projectname
  1. Copy the boilerplate Drupal 7 Lando config and paste into a .lando.yml file in the gitroot directory.
curl -o .lando.yml https://gitlab.agile.coop/agile-public/lando/raw/master/d7/.lando.yml

  1. Edit the .lando.yml file and change the value for the name key so that it follows the convention [client code][project code].

    Also change the domain name for mailhog under the proxy key. The mail.projectname.lndo.site domain name should be updated so that projectname is something unique to the project, using the name value is preferable.

Note that Lando will remove any non alpha characters from domain names so if you wrote agile-collective for the project name the domain name will be agilecollective.lndo.site. You can confirm the domain name with lando info.

  1. Check the PHP version the server uses by visiting the status page on the production site at: /admin/reports/status. Then change the PHP version if needed in the .lando.yml file:
  config:
    php: '5.6'
  1. (Optional) Modify the .lando.yml file for this project's particular needs. For example, the project may need Solr. See the Lando docs for details on how to add services.
  2. Configure the domain for drush and Lando by creating a .env file with the following content (edit the domain to suit your project, can be discovered with lando info). You should replace projectname with whatever you chose for the .lando.yml file:
echo "DRUSH_OPTIONS_URI=http://projectname.lndo.site" >> .env
  1. Add the web root as a environment variable so that drush commands can be run from outside the webroot.
echo "DRUSH_OPTIONS_ROOT=/app/web" >> .env
  1. Bring the Lando containers up:
lando start
  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. Modify the .gitignore file to ignore the .env file and sql files:
# Ignore .env files as they are personal
/.env

# Ignore most sql file variations
*.sql
*.sql.gz
*.sql.tgz
*.mysql
  1. Download the boilerplate settings.php file:
curl -o web/sites/default/settings.php https://gitlab.agile.coop/agile-public/lando/raw/master/d7/settings.php
  1. Create the drush aliases:
mkdir -p drush/sites;
curl -o drush/drushrc.php https://gitlab.agile.coop/agile-public/lando/raw/master/d7/drushrc.php;
curl -o drush/sites/remote.aliases.drushrc.php https://gitlab.agile.coop/agile-public/lando/raw/master/d7/remote.aliases.drushrc.php;
curl -o drush/sites/server.aliases.drushrc.php https://gitlab.agile.coop/agile-public/lando/raw/master/d7/server.aliases.drushrc.php
  1. Edit the two drush alias files (in drush/sites/) and enter the correct details for the remote server. More detailed information about the contents of these files and the set up of aliases can be found in the drush alias set up document.
  2. Import the database. This can be done with one of the following two methods:
  1. Access your site (run this command from the web root):
lando drush uli
  1. Commit the .gitignore and .lando.yml file to the repository (run this from the git root):
git add .lando.yml .gitignore
git commit -m "Adds .lando.yml file and updates gitignore"
git push origin master
git checkout develop
git merge master
git push origin develop
git checkout master
  1. Note the project shortname in the support master sheet.
  2. Go to the front end set up documentation and configure the theme to work with Lando. Commit any changes.

Drupal 6

While Drupal 6 is not supported sometimes you may need to set up a D6 site for a site audit or migration project.

You can follow a mix of the Drupal 7 set up and the official Drupal 6 guide from Lando.

Last updated: