Information for: DEVELOPERS   PARTNERS

Configuration management for Drupal 8 and Drupal 9

Starting with Drupal 8, Drupal’s configuration management (CM) makes major improvements to how Drupal manages configuration, compared to earlier Drupal versions. This page describes the best ways to handle configuration management for websites running Drupal 8 or greater on Cloud Platform.

Note

  • These examples require the Cloud Platform Drush integration aliases.
  • These examples assume you are using Cloud Platform as your development environment. If you are using a local development environment, see Managing configuration in local development.
  • Although, by default, websites running Drupal 8 or greater use the sync configuration directory type for configuration, Cloud Platform uses the vcs configuration directory type for that purpose.

Required config/default folder

For websites running Drupal 8 or greater, Cloud Platform requires you to define a default location for the configuration directory where you will store Drupal configuration information in your code repository. This directory is typically in the following location:

config/[sitename]

where config is a directory at the same level (sibling) of your docroot directory. You must create the directory, as it doesn’t exist by default in the repository. If you don’t create the config directory, Cloud Platform may display a runtime error message like the following, which indicates you can’t run update.php until you create the directory:

The directory docroot/../config/default does not exist.

You can’t commit empty directories in Git. You must also add a small file (typically a text file named .gitkeep) to the new directory before you can commit the directory to your repository.

After you create the directory, the file structure at the docroot level should be similar to the following:

/docroot/
config/default/

For Site Factory subscribers

Site Factory subscribers must also create a post-settings-php hook as described in Configuration management directory.

Pushing configuration forward

In this scenario, we assume you are building or updating a Drupal 8 or Drupal 9 application named example in an Cloud Platform Development environment.

  1. In your Development environment, use the tools of your choice to set the configuration of all the modules in your Drupal application.

  2. If you are satisfied with the configuration, switch your Development environment to Live Development mode, as described in Using Live Development mode to change code on your server.

  3. In Live Development mode, export your application’s configuration from the database to the file system using a command like the following example:

    drush @example.dev.livedev config-export vcs --commit
    
  4. You can then review the changes before pushing them:

    drush @example.dev.livedev ssh git show
    
  5. If you’re satisfied with the changes, push them using a command like the following example:

    drush @example.dev.livedev ssh git push
    

    If you aren’t satisfied with your changes, run commands based on the following to remove them:

    drush @example.dev.livedev ssh git reset --hard HEAD^1
    drush @example.dev.livedev config-export vcs
    

    Adjust your changes as needed, and then run the following commands:

    drush @example.dev.livedev config-export vcs --commit
    drush @example.dev.livedev ssh git push
    
  6. Sign in to Cloud Platform and select your application.

  7. Drag the Code element from Dev to Stage to push your configuration from the Development environment to the Staging environment.

  8. Import the configuration from the file system to the database for the Staging environment by running a command like the following example:

    drush @example.test config-import vcs
    
  9. If required by your configuration changes, run update on your Staging environment with a command like the following example:

    drush @example.test updatedb
    

Pulling configuration from Production to Development

This scenario assumes that you have made configuration changes in a Drupal 8 or Drupal 9 application named example in an Cloud Platform Production environment and you want to pull them back into your Development environment, so your development workflow uses the current live configuration.

  1. Set your Development environment to Live Development mode.

  2. Copy the configuration from your Production environment to the vcs configuration directory type folder on the Development environment by executing a command like the following example on your local computer:

    drush config-pull @example.prod @example.dev.livedev --label=vcs
    
  3. Commit the configuration on the Development environment by executing a command like the following example on your local computer:

    drush @example.dev.livedev ssh git commit -am "Copy config from Prod."
    
  4. Import the copied configuration into the Development environment by executing a command like the following example on your local computer:

    drush @example.dev.livedev config-import vcs
    
  5. If all went well, run:

    drush @example.dev.livedev ssh git push
    

    If not, run:

    drush @example.dev.livedev ssh git reset --hard HEAD^1
    

Managing configuration in local development

If you’re developing a Drupal 8 or Drupal 9 application in a local environment, keep in mind the following tips:

  • Download the Cloud Platform Drush integration aliases. For more information, see Using Drush aliases.

  • Set the configuration directory.

  • In the settings.php file for your application, define a sync key:

    $config_directories['sync'] = $app_root . '/../config/' . basename($site_path);
    
  • Replace @example.dev.livedev with @self in the earlier procedures on this page.

Whenever you update the code in an environment, run the following:

drush config-import vcs -y && drush updatedb -y

Set the configuration directory

You must add the entry for setting the configuration directory to the end of the settings.php file for your application. The format will depend on your Drupal version.

Drupal 8.8.0: The $config_directories variable is deprecated. The sync directory and vcs directory paths are now defined as values in the $settings array:

$settings['config_sync_directory'] = 'your/config/sync/directory/path'
$settings['config_vcs_directory'] = 'your/config/vcs/directory/path'

Drupal 8.7 and earlier versions: You must define the $config_directories variable to contain the names of the directories in which the configuration files are located.

$config_directories['vcs'] = $app_root . '/../config/' . basename
($site_path);

Protecting configuration in the Production environment

You can protect your Production environment from untested configuration changes by using the Configuration Read-only mode module.