Configuration Workflow for Drupal 8 Sites
Commit your Drupal configuration to version control.
Managing configuration is an extremely important part of any team website project, but in many cases, this area of the project does not receive as much attention as it deserves. The tools for Drupal 7 do not provide complete coverage of all configuration settings, leading to inconsistencies in configuration handling and inconvenient workarounds. This has led to configuration management becoming a real thorn in the side for many projects.
Pantheon supports the Drupal 8 Configuration Management system and defaults configuration into the
sites/default/config directory for each Pantheon Drupal 8 site. You can export your configuration into that directory directly using Drush's config-export command or indirectly using Drupal's UI to download the configuration and then use SFTP/Git to place the configuration in
sites/default/config. For more information on how this all works, check out Matt Cheney and David Strauss' presentation on Drupal 8 CMI on Managed Workflow at Drupalcon Amsterdam.
With the Development environment in SFTP mode, export your configuration to code:
drush cex -y
Return to the Dashboard and commit the configuration changes.
- Deploy the code to Test.
Import the configuration from code into the test environment database:
drush cim -y
Test the site.
- Deploy the code to Live.
Import the configuration from code into the live environment database:
drush cim -y
Using Terminus, you can complete the above process from the command line.
In the commands below, replace
site with your site name and the correct environment:
terminus drush <site>.dev -- cex -y
terminus env:commit <site>.dev --message="Export configuration to code"
terminus env:deploy <site>.test --sync-content --cc --updatedb --note="Deploy configuration to test"
terminus drush <site>.test -- cim -y
terminus env:deploy <site>.live --cc --note="Deploy configuration to live"
terminus drush <site>.live -- cim -y
Configuration Tools for Drupal 8
With Drupal 8, much more powerful tools promise to greatly improve this situation. The new configuration management system provides complete and consistent import and export of all configuration settings, and Git already provides facilities for managing parallel work on different branches. When conflicts occur, it is possible to back out the conflicting changes, take just the version provided in the central repository, or use three-way merge tools such as
kdiff3 to examine and manually resolve each difference. A new Drush project, config-extra, includes a
config-merge command that streamlines the use of these tools.
Config Direct Save Module
If you prefer to use a GUI to manage configuration management, try the Config Direct Save Module, available on Drupal.org. Activating this module creates a new Update menu option under your configuration menu. This module can make backups of configurations (when you check the backup check box) and override the sync (all files with old configuration) by the new configurations (replace all configurations files).
Drush Config Workflow
Even with tools, a project needs to make a plan to manage the configuration workflow. To help projects get started, Pantheon has set up a public repository called Drush Config Workflow. This repository contains documentation on a couple of different configuration workflows that can be used during different phases of a project.
The Git configuration workflow describes how to use
config-merge to export your configuration changes, commit them to Git, push them to the central repository, pull the changes locally, and then merge them with your local development site’s configuration. All of this is done in a single command.
The rsync configuration workflow allows you to use a similar workflow in situations where you cannot make commits on the remote Drupal site. In these instances,
config-merge will export changes to a temporary directory and then rsync them to the local system, where they are committed to a temporary branch in Git and then merged with the local configuration changes.
Additionally, the three-way merge page in this repository describes what to do when the
config-merge tool encounters a conflict, and brings up a three-way merge tool such as kdiff3. This tool can considerably reduce the time needed to comprehend and resolve merge conflicts.
If you would like to try out any of the example scenarios presented in the repository, there is also a handy installation script that will quickly set up a local environment for you to use. It can be used to either clone a Pantheon site locally, or it can create both sites locally. Instructions on how to use the script are detailed on the installation page.
Relocated Configuration Directory
Configuration files can contain sensitive information. Drupal takes some measures to protect the default configuration directory, but the conventional way to secure these files is to locate them outside of the document root so they are not web accessible. Following this convention may help make site configuration easier to manage.
Before you Begin
- Refer to Serving Sites from the Web Subdirectory to enable nested docroot on a new or existing Drupal 8 site.
Configure and Relocate
After implementing a nested docroot, set a new path (
/config) for configuration directories by adding the following to
/** * Place the config directory outside of the Drupal root. */ $config_directories = array( CONFIG_SYNC_DIRECTORY => dirname(DRUPAL_ROOT) . '/config', );
Care should be taken to ensure that this code is added after the
settings.pantheon.php is included; otherwise, the
CONFIG_SYNC_DIRECTORY will be overwritten with the Pantheon default value. The configuration directory must exist before this variable is changed.
Relocate the configuration directory for the default location using
$ git mv web/sites/default/files/config .
For additional details, see this blog post by Greg Anderson.