Pantheon et Lando Documentation

Pantheon Lando Documentation

Working with Pantheon

Lando offers a configurable recipe for spinning up apps that closely mimic the Pantheon environment. Let’s go over some basic usage.

You should also check out Pantheon’s local dev docs.

Getting Started

Before you can use all the awesome Lando magic you need a codebase with a .lando.yml file in its root directory. There are a few ways you can do this…

1. Start a codebase that already has a .lando.yml

# Clone pantheon codebase from git
# See: http://ift.tt/2wKOIYf
git clone ssh://codeserver.dev.PANTHEONID@codeserver.dev.PANTHEONIDdrush.in:2222/~/repository.git mysite

# Go into the cloned site
cd mysite

# Start the site
lando start

# Authorize with pantheon
# NOTE: if you dont do this step you wont be able to do `lando pull/push/switch`
# NOTE: you need to put in the actual machine-token here, not the email
lando terminus auth:login --machine-token=MYSPECIALTOKEN

2. Init a codebase that doesn’t yet have a .lando.yml

# Clone a codebase from some git repo
git clone /path/to/git/repo mysite

# Go into the cloned site
cd mysite

# Initialize a .lando.yml for this site
# NOTE: You will need to choose the pantheon site that makes sense
lando init --recipe pantheon

3. Get your site from Pantheon

# Create a folder to clone your site to
mkdir mysite && cd mysite

# Initialize a Pantheon .lando.yml after getting code from Pantheon
# This require a Pantheon Machine Token
# See: http://ift.tt/2wKJBXV
lando init pantheon

4. Get your site from GitHub

# Create a folder to clone your site to
mkdir mysite && cd mysite

# Initialize a Pantheon .lando.yml after getting code from GitHub
# This require a GitHub Personal Access Token
# See: http://ift.tt/2wc8ng2
lando init github --recipe pantheon

Once you’ve initialized the .lando.yml file for your app you should commit it to your repository. This will allow you to forgo the lando init step in subsequent clones.

Starting Your Site

Once you’ve completed the above you should be able to start your Pantheon site.

AT THIS TIME WE WILL NOT AUTOMATICALLY PULL YOUR DATABASE AND FILES

You can read below on how to do that with our helper pull command or via a manual import.

If your Pantheon site has a composer.json Lando will attempt to run composer install on it automatically.

lando start

If you visit any of the green-listed URLs that show up afterwards you should be welcomed with the Drupal, Backdrop or WordPress installation screens. Read below on how to import your database and file so you can visit your site like it exits on Pantheon.

Importing Your Database and Files

Once you’ve started up your Pantheon site you will need to pull in your database and files before you can really start to dev all the dev. There are two easy ways to do this…

1. Using lando pull

Lando provides a command for Pantheon sites called lando pull to get your database and files. If you do not specify --code, --database or --files then lando will use the environment associated with your currently checked out git branch.

Please consult the manual import documentation below if this command produces an error.

Usage

# Pull the latest code, database and files
# This will pull the environment associated with your currently checked out git branch
lando pull

# Skip a code merge
lando pull --code=none

# Pull only the database from the test environment
lando pull --database=test --files=none

# Pull only the files
lando pull --database=none

# Pull only the latest files without grabbing a files backup
lando pull --database=none --rsync

Options

--code, -c      The environment to get the code from or [none]
--database, -d  The environment to get the db from or [none]
--files, -f     The environment to get the files from or [none]
--rsync         Rsync the files, good for subsequent pulls                                                  [boolean] [default: false]

2. Manually Importing Your DB and Files

You will want to the replace MYSITE and MYENV below with the Pantheon site and environment from which you want to import.

Database

# Remove lingering DB dumps
lando ssh -c "rm -f /app/database.sql.gz"

# Create a new backup of your database
# If you've created a db backup recently this step is not needed.
lando terminus backup:create MYSITE.MYENV --element=db

# Download and import backup of the database
lando terminus backup:get MYSITE.MYENV --element=db --to=/app/database.sql.gz
lando db-import database.sql.gz

You can learn more about the db-import command over here

Files

# Remove the DB dump
lando ssh -c "rm -f /tmp/files.sql.gz"

# Create a new backup of your files
# If you've created a files backup recently this step is not needed.
lando terminus backup:create MYSITE.MYENV --element=files

# Download and extract backup of the files
lando terminus backup:get MYSITE.MYENV --element=files --to=/tmp/files.tar.gz
lando ssh -c "mkdir -p \$LANDO_WEBROOT/\$FILEMOUNT"
lando ssh -c "tar -xzvf /tmp/files.tar.gz -C \$LANDO_WEBROOT/\$FILEMOUNT --strip-components 1"

You can alternatively download the backup and manually extract it to the correct location.

Pushing Your Changes

While a best practices workflow suggests you put all your changes in code and push those changes with git, Lando provides a utility comand for pantheon recipes called lando push that pushes up any code, database or files changes you have made locally. If you do not specify --database or --files then lando will use the environment associated with your currently checked out git branch.

Usage

# Push the latest code, database and files
# This will push the environment associated with your currently checked out git branch
lando push

# Push the latest code, database and files with a description of the change
lando push -m "Updated the widget to do awesome feature x"

# Push only the database
lando push --files=none

# Pull only the files
lando push --database=none

Options

--message, -m   A message describing your change [default: "My awesome Lando-based changes"]
--database, -d  The environment to push the db to or [none]
--files, -f     The environment to push the files to or [none]

Working With Multidev

Pantheon multidev is a great (and easy) way to kickstart an advanced dev workflow for teams. By default lando will pull down your dev environment but you can use lando switch <env> to switch your local copy over to a Pantheon multidev environment.

Usage

# Switch to the env called "feature-1"
lando switch feature-1

# Swtich to the env called "feature-1" but ignore grabbing that env's files and database
# Note that this is basically a glorified `get fetch --all && git checkout BRANCH`
lando switch feature-1 --no-db --no-files

Options

  --no-db     Do not switch the database              [boolean] [default: false]
  --no-files  Do not switch the files                 [boolean] [default: false]

Tooling

Each Lando Pantheon recipe will also ship with the Pantheon toolchain. This means you can use drush, wp-cli and terminus via Lando and avoid mucking up your actual computer trying to manage php versions and tooling.

lando composer                 Run composer commands
lando db-import <file>         Import <file> into database. File is relative to approot.
lando db-export                Export a database. Resulting file: {DB_NAME}.TIMESTAMP.gz
lando drush                    Run drush commands
lando mysql                    Drop into a MySQL shell
lando php                      Run php commands
lando pull                     Pull code, database and/or files from Pantheon
lando push                     Push code, database and/or files to Pantheon
lando redis-cli                Run redis-cli commands
lando switch <env>             Switch to a different multidev environment
lando terminus                 Run terminus commands
lando varnishadm               Run varnishadm commands
lando wp                       Run wp-cli commands

Tools are dependent on framework

Lando will load up tools that are appropriate to the framework you specified in the recipe config section of your .lando.yml. eg. wp-cli will be available for WordPress sites and Drush will be available for Drupal sites.

# Login to terminus with a machine token
lando terminus auth:login --machine-token=MYSPECIALTOKEN

# Get a list of wp-cli commands
lando wp

# Download a dependency with drush
lando drush dl views

# Download a dependency with composer
lando composer config repositories.drupal composer http://ift.tt/2aXpkBN
lando composer require "drupal/search_api_pantheon ~1.0" --prefer-dist

# Download a backdrop dependency
lando drush dl webform

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

Configuration

Recipe

You can also manually configure the .lando.yml file.

# Pantheon recipe
name: pantheon

# Start with the default Pantheon recipe
recipe: pantheon

# Configure the Pantheon recipe
config:

  # Optionally specify the type of Pantheon site this is. If ommitted this will
  # default to `drupal`. You can use the following options
  #
  #   - `backdrop`
  #   - `drupal` (for Drupal 6 and Drupal 7 sites)
  #   - `drupal8`
  #   - `wordpress`
  #
  framework: drupal8

  # Optionally activate xdebug
  xdebug: true

  # Optionally specify the site id, name and environment for your Pantheon site
  #
  # This is helpful for running terminus commands or performing similar operations
  id: 7587b3ea-95b6-44ab-b36b-6ebd9c3e9866
  site: kalabox-drupal7
  env: dev

You will need to rebuild your app with lando rebuild to apply the changes to this file. You can check out the full code for this example over here.

pantheon.yml

If you want to change your php version or make use of a nested docroot, you will want to do that in your pantheon.yml file just like you would on Pantheon itself.

api_version: 1

# PHP Version:
# http://ift.tt/2wbyzHv
# Set site's PHP version to 7.0
php_version: 7.0

# Drush Version
# http://ift.tt/2wKrO39
drush_version: 8

# Protected Web Paths
# http://ift.tt/2wbyAex
# protected_web_paths:
#   - /example.txt
#   - /example_directory

# Nested Docroot
# http://ift.tt/2wKnroB
web_docroot: true

# Quicksilver Platform Integration Hooks
# http://ift.tt/2wbIrAY
# workflows:

A lando restart or lando rebuild is needed to apply these changes.

Environment Variables

Like Pantheon, Lando will also inject variables into your runtime container so that you have useful information stored about your app. These are stored directly in the environment (eg accessible via getenv()), $_ENV, $_SERVER or as defined php constants.

Here is a non-exhuastive list of some of the most commonly used config.

# Site info
PANTHEON_BINDING: lando
PANTHEON_ENVIRONMENT: lando
PANTHEON_SITE_NAME: Your Pantheon site name
PANTHEON_SITE: Your Panthen UUID
FILEMOUNT: The location of your files directory
DOCROOT: /
FRAMEWORK: Either drupal, drupal8, backdrop, or wordpress
HTTP_X_SSL: ON or undefined
HTTPS: on or undefined

# Cache connection info
CACHE_HOST: cache
CACHE_PASSWORD:
CACHE_PORT: 6379

# DB connection info
DB_HOST: database
DB_PORT: 3306
DB_NAME: pantheon
DB_PASSWORD: pantheon
DB_USER: pantheon

# Index connection info
PANTHEON_INDEX_HOST: index
PANTHEON_INDEX_PORT: 449

# WordPress things
AUTH_KEY: Needed for WordPress. We set this automatically.
AUTH_SALT: Needed for WordPress. We set this automatically.
LOGGED_IN_KEY: Needed for WordPress. We set this automatically.
LOGGED_IN_SALT: Needed for WordPress. We set this automatically.
NONCE_KEY: Needed for WordPress. We set this automatically.
NONCE_SALT: Needed for WordPress. We set this automatically.
SECURE_AUTH_KEY: Needed for WordPress. We set this automatically.
SECURE_AUTH_SALT: Needed for WordPress. We set this automatically.

# Drupal/Backdrop things
BACKDROP_SETTINGS: JSON object of Backdrop config and settings.
PRESSFLOW_SETTINGS: JSON object of Drupal config and settings.
DRUPAL_HASH_SALT: Needed for Drupal8. We set this automatically.

These are in addition to the default variables that we inject into every container. Note that these can vary based on the choices you make in your recipe config.

Automation

You can take advantage of Lando’s events framework to automate common tasks. Here are some useful examples you can drop in your .lando.yml to make your Pantheon app super slick.

Note that these suggestions are framework specific and that you can only define each event hook once, unlike below.

events:

  # Runs composer install and npm install/npm compile-sass after you start
  # NOTE: this assume you've set up a node cli container called `node` with `gulp`
  # installed globally and a sass compile task called `gulp sass`
  post-start:
    - appserver: cd $LANDO_MOUNT && composer install
    - node: cd $LANDO_WEBROOT/path/to/theme && npm install
    - node: cd $LANDO_WEBROOT/path/to/theme && gulp sass

  # Runs wp search-replace after you do a pull
  post-pull:
    - appserver: wp search-replace OLDURL NEWURL

  # Does a features revert clear cache after a pull
  post-pull:
    - appserver: cd $LANDO_WEBROOT && drush fra -y
    - appserver: cd $LANDO_WEBROOT && drush cc all -y

  # Does a config import clear cache after a pull
  post-pull:
    - appserver: cd $LANDO_WEBROOT && drush config-import -y
    - appserver: cd $LANDO_WEBROOT && drush cr

  # Does a config export before a push
  pre-push:
    - appserver: cd $LANDO_WEBROOT && drush config-export -y

  # Clears the remote sites cache and updates its db after a push
  post-push:
    - appserver: drush @pantheon.MYSITE.MYENV drush updb -y
    - appserver: drush @pantheon.MYSITE.MYENV drush cr

Advanced Service Usage

Lando attempts to closely mimic the Pantheon environment. Please review the following docs to get a better handle on how Pantheon works:

What works on Pantheon should also work on Lando.

You can get more in-depth information about the services this recipe provides by running lando info.

Next Steps

 

Tags:
September 07, 2017 at 10:13AM
Open in Evernote

Share

Leave a comment