# Lagoon (beta)

Lagoon solves what developers are dreaming about: A system that allows developers to locally develop their code and their services with Docker and run the exact same system in production. The same Docker images, the same service configurations and the same code.

This is currently an beta level integration that has the following serious caveats:

• This does not support Lagoon's elasticsearch, mongodb, or rabbitmq containers yet
• It's not yet clear how much customization to your project is currently supported

However, if you'd like to try it out and give your feedback on what worked and what didn't then please continue.

You can report any issues or feedback over here.

# Getting Started

Before you get started with this recipe we assume that you have:

1. Installed Lando and gotten familiar with its basics
2. Initialized a Landofile for your codebase for use with this recipe
3. Read about the various services, tooling, events and routing Lando offers.
4. Temporarily stopped (pygmy stop) the Pygmy tool to avoid any port conflicts

However, because you are a developer and developers never ever RTFM, you can also run the following commands to try out this recipe against the amazee.io Drupal Example.

# Clone a site from a lagoon instance
lando init --source lagoon

# Start it up
lando start

# Pull down files and database
lando pull --database main --files main

# List information about this apps services.
lando info

# 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. To see labels in action check out 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

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:

• PHP-FPM
• PHP CLI
• Nginx
• MariaDB
• PostgreSQL
• Redis
• Solr
• Varnish

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

# External access

If you would like to connect to your database, or some other service, from your host using a GUI client like SequelPro, you can run lando info and use the external_connection information and any relevant creds for the service you want to connect to.

You can also check out the environment variable LANDO INFO, which is available in every Lando container, as it contains useful information about how your application can access other Lando services.

Some example connection info for the mariadb service is shown below:

lando info --service mariadb --format default

[ { service: 'mariadb',
    urls: [],
    type: 'lagoon-mariadb',
    healthy: true,
    creds: { user: 'drupal', password: 'drupal', database: 'drupal', rootpass: 'Lag00n' },
    internal_connection: { host: 'mariadb', port: '3306' },
    external_connection: { host: '127.0.0.1', port: '32790' },
    config: {},
    version: 'custom',
    meUser: 'mysql',
    hostnames: [ 'mariadb.drupalexample.internal' ] }]

# Tooling

Each Lando Lagoon recipe will also ship with the Lagoon toolchain. This means you can use drush and other tools via Lando and avoid mucking up your actual computer trying to manage php versions and tooling. Here are the things that ship with the drupal flavor by default.

You can also run lando from inside your app directory for a complete list of commands.

lando composer          Runs composer commands
lando db-export [file]  Exports database from a database service to a file
lando db-import <file>  Imports a dump file into a database service
lando drush             Runs drush commands
lando lagoon            Runs lagoon commands
lando mysql             Drops into a MySQL shell on a database service
lando node              Runs node commands
lando npm               Runs npm commands
lando php               Runs php commands
lando yarn              Runs yarn commands

Note that you can define your own commands by using out tooling framework. Also check out the guides for the powerful DB Export and DB Import commands.

Also, check out the Lagoon CLI Docs for more information on using lando lagoon.

# Mailhog

If you're using a Lagoon php container we will automatically set up mailhog for you so you can capture emails. You will see urls to access its web interface after you run lando start or if you run lando info.

NAME          drupal-example
LOCATION      /Users/pirog/work/lando/examples/lagoon-drupal/drupal
SERVICES      cli, nginx, php, mariadb, redis, solr, mailhog
MAILHOG URLS  http://localhost:32792
              http://inbox.drupal-example.lndo.site/

# Pulling and pushing databases and files

Lando also provides wrapper commands called lando pull and lando push.

With lando pull you can import data and download files from your remote Lagoon site. With lando push you can do the opposite, export data or upload files to your remote Lagoon site.

lando pull

Pull db and files from Lagoon

Options:
  --help          Shows lando or delegated command help if applicable
  --verbose, -v   Runs with extra verbosity
  --auth          Lagoon key
  --database, -d  The environment from which to pull the database
  --files, -f     The environment from which to pull the files

# Interactively pull databases and files
lando pull

# Import the remote database and files from the main environment
lando pull -d main -f main

# Effectively "do nothing"
lando pull --database none --files none

lando push

Push db and files to Lagoon

Options:
  --help          Shows lando or delegated command help if applicable
  --verbose, -v   Runs with extra verbosity
  --auth          Lagoon key
  --database, -d  The environment to which the database will be pushed
  --files, -f     The environment to which the files will be pushed

# Interactively push databases and files
lando push

# Export the local database and files to the main environment
lando push -d main -f main

# Effectively "do nothing"
lando push --database none --files none