DDEV + Pantheon Integration

Published May 13, 2022

Reposted with permission from Pantheon.io.

Automating the Process of Keeping Your Local Environment Up-to-date

DDEV is a Docker-based local development environment solution that allows developers to run local copies of all their Drupal and WordPress projects in a personal development environment. Much like similar Docker-based solutions, DDEV hides most of the complexity of Docker — allowing Drupal and WordPress developers to focus on what they like best.

What Problem Are We Solving?

One of the typical challenges that a developer faces when working on their local development environment is keeping their local database and content files up-to-date with a remote environment (development, test, or live). For the database, the manual process normally involves downloading a database dump and importing it into the local development environment.

DDEV's "provider" functionality automates the steps into a single "ddev pull" command that can authenticate with a remote server, download the most recent database backup, and then import it into the local environment -— all with just a single command!

How Exactly Does It Work?

DDEV includes sample provider integrations for Drupal (but not WordPress yet); they are located in your DDEV project's .ddev/providers/ directory. Each provider integration includes documentation, as well as the complete code for the integration — making it easy for you to customize.

A DDEV community member, Matthias Andrasch, has been working on DDEV provider integration for WordPress; find them here. These are not officially supported, so please use them with caution.

The Pantheon integration requires that a Pantheon machine token be created and added to your machine's ~/.ddev/global_config.yaml file in the following format:

- TERMINUS_MACHINE_TOKEN=abcdeyourtoken`

This allows DDEV to access your Pantheon projects via Terminus (built-in to DDEV), in order to access database and content file backups.

The Pantheon integration also requires that you have Drush installed as part of the Drupal project. If you don't, then it's easy to add via:

$ ddev composer require drush/drush

For basic integration, you'll just need to copy the example.pantheon.yaml provider file to pantheon.yaml and then update the site name and environment variable. This allows you to target exactly which site and Pantheon environment you'd like to access the database backup and content files from when running the "ddev pull" command.

  project: de8.live

In this example, the machine name of Pantheon project is "de8" and we're going to be updating the local DDEV environment with database and content files backups from the Pantheon Live environment.

Once configured, to update your local database and content files, run "ddev pull pantheon" and you’re set. If you don't want to sync the content files to your local, then you can add the "--skip-files" parameter.

This is a summary of the integration steps — for all the details, be sure to check out the .ddev/providers/example.pantheon.yaml file in your DDEV project.

Dive Deeper

As mentioned earlier, the example.pantheon.yaml file doesn't just include the parameters for the provider integration, it also contains the actual commands for each step of the integration.

For example, in the "ddev_pull_command" section, you can see the various bash commands used to obtain a database backup from Pantheon:

  command: |
    # set -x   # You can enable bash debugging output by uncommenting
    ls /var/www/html/.ddev >/dev/null # This just refreshes stale NFS if possible
    pushd /var/www/html/.ddev/.downloads >/dev/null
    terminus backup:get ${project} --element=db --to=db.sql.gz

If you speak Terminus, then you'll notice that the command doesn't actually create a new database backup, but rather downloads the most recent. But, since all of the commands are specified here, you can add a "terminus backup:create" command if desired.

It is important to note that DDEV provider integration also includes a "ddev push" command that does exactly what you think it does — it allows you to easily push a local database or content files directory to a remote Pantheon environment. As this violates the recommended "code flows up, data flows down" principle, I don't recommend using it — or at least use it with extreme caution.

Next Steps

If this level of local development environment automation isn't enough for you, then your next step would probably be to think about using the "ddev pull" command as part of a DDEV post-start command hook (or custom DDEV command) that automatically calls "ddev drush cr" "ddev drush cim" immediately after the "ddev pull" command. This makes it possible to easily have a fresh local development environment every time you start working on your project!

Sign up to receive email notifications of whenever we publish a new blog post or quicktip!