Configuration

While Lando recipes set sane defaults so they work out of the box, they are also configurable.

Here are the configuration options, set to the default values, for this recipe's Landofile. If you are unsure about where this goes or what this means we highly recommend scanning the recipes documentation to get a good handle on how the magicks work.

recipe: lagoon
config:
  build:
    - composer install

If you do not already have a Landofile for your Lagoon site, we highly recommend you use lando init to get one as that will automatically populate the above defaults for you. Manually creating a Landofile with these things set correctly can be difficult and is highly discouraged.

Note that if the above config options are not enough, all Lando recipes can be further extended and overriden.

Setting Lagoon labels

Under the hood the lagoon recipe uses special Docker labels to connect Lagoon services to Lando ones. If your project uses one of the Amazee.io starting templates like this one for Drupal 9 then you should be good to go, no further setup is required.

However, if you are using a legacy template or a bespoke Lagoon setup then you will need to manually add these labels into your Lagoon's docker-compose.yml. Here is an example of a docker-compose.yml with non-essential config removed for readability.

services:
  cli: # cli container, will be used for executing composer and any local commands (drush, drupal, etc.)
    labels:
      # Lagoon Labels
      lagoon.type: cli-persistent
      # Lando type label
      lando.type: php-cli-drupal

  nginx:
    labels:
      lagoon.type: nginx-php-persistent
      lando.type: nginx-drupal

  php:
    labels:
      lagoon.type: nginx-php-persistent
      lando.type: php-fpm

  mariadb:
    image: uselagoon/mariadb-drupal:latest
    labels:
      lagoon.type: mariadb
      lando.type: mariadb-drupal
    ports:
      - "3306" # exposes the port 3306 with a random local port, find it with `docker-compose port mariadb 3306`
    << : *default-user # uses the defined user from top
    environment:
      << : *default-environment

For the most up to date list of supported labels, check out this. You can see the labels in action on the official Amazee.io Drupal 9 Lagoon example.

Also note that Lando additionally supports lagoon.type === none as documented over here.

Build steps

If you have steps you need to run to get your site into a workable place you can put them in the build key of your recipes config. By default, we will run composer install but you may wish to augment that with any front end compilation tasks you may have as in the example below:

recipe: lagoon
config:
  build:
    - composer install
    - yarn run compile:sass
    - drush sql-sync my-database

These will run against the Lagoon PHP CLI Drupal container so you will have access to all the tools there as well as the ones it inherits from the base PHP CLI container.

Note that these will run the first time you run lando start. You will need to run lando rebuild to trigger them again if you make changes.

Customizing the stack

Customizations not fully tested

We think most of the customizations below should work but they have been very minimally tested. If you try one and it doesn't work, please report an issue.

Lando will read and interpret your normal .lagoon.yml and its associated Docker Compose files. This means that you should be able to do the customizations Lagoon has documented, run a lando rebuild and see the changes. Lando reads the lando.type labels from the docker-compose file to ensure that the correct image is used for a service.

The services we currently support with links to their associated Lagoon docs is shown below:

• Elasticsearch
• MariaDB
• Node
• Nginx
• PHP CLI
• PHP-FPM
• Python
• PostgreSQL
• Redis
• Ruby
• Solr*
• Varnish

Note that we are testing against the "Drupal" variants of the above but it's possible the base services work as well.

*Please note: if using uselagoon/solr-8-drupal you will need to add the following command to your Solr service in your .lando.yml file. Alternate Solr images are supported and may require different commands, this is just one example.

recipe: lagoon
services:
  solr:
    command: solr-precreate drupal /solr-conf

Customizing your domain or using a non lndo.site domain

As per the general Lando Proxy instructions, it is possible to configure custom domains (i.e. myapp.lndo.site or foo.bar.xyz) for your site. However, as the default Lagoon base images are built slightly differently to the default Lando ones, you need to specify the port to route the request to (usually 8080 for nginx):

Add the following lines to your .lando.yml file

proxy:
  nginx:
    - myapp.lndo.site:8080
    - foo.bar.xyz:8080

Your app can then be accessed via the myapp.lndo.site or foo.bar.xyz URL. Note that this will override any autogenerated URLs.