Information for: DEVELOPERS   PARTNERS   SUPPORT

Configuration management for Drupal

Important

This page describes the best ways to handle configuration management for websites running Drupal 8 or later on Acquia Cloud Platform.

Drupal’s configuration management (CM) makes major improvements to how Drupal 8 manages configuration, compared to earlier Drupal versions.

Note

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

Required config/default folder

For websites running Drupal 8 or later, Acquia Cloud Platform requires you to define a default location for the configuration directory where you store Drupal configuration information in your code repository. Typically, this directory is 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 does not exist by default in the repository. If you do not create the config directory, Acquia Cloud Platform displays the following error message:

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

You cannot run update.php until you create the config directory.

You cannot 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 is as follows:

/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

To explain this scenario, let us assume that you want to build or update a Drupal 9 application named example in the Development environment in Acquia Cloud Platform.

To push the configuration forward:

  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 the Live Development mode. For more information, see Using Live Development mode to change code on your infrastructure.

  3. In the Live Development mode, export your application’s configuration from the database to the file system:

    drush @example.dev.livedev config-export vcs --commit
    
  4. Review the changes before pushing them:

    drush @example.dev.livedev ssh git show
    
  5. If you are satisfied with the changes, push them:

    drush @example.dev.livedev ssh git push
    

    If you are not satisfied with your changes:

    1. Remove the changes:

      drush @example.dev.livedev ssh git reset --hard HEAD^1
      drush @example.dev.livedev config-export vcs
      
    2. Adjust your changes and run the following commands:

      drush @example.dev.livedev config-export vcs --commit
      drush @example.dev.livedev ssh git push
      
  6. Sign in to the Acquia Cloud Platform user interface 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:

    drush @example.test config-import vcs
    
  9. If required by your configuration changes, run update on your Staging environment:

    drush @example.test updatedb
    

Pulling configuration from Production to Development

To explain this scenario, let us assume that you made configuration changes in a Drupal 9 application named example in the Production environment in Acquia Cloud Platform, and you want to pull them back into your Development environment. This ensures that your development workflow uses the current live configuration.

To pull the configuration from the Production environment to the Development environment:

  1. Set your Development environment to the Live Development mode.

  2. Copy the configuration from your Production environment to the vcs configuration directory type folder on the Development environment:

    drush config-pull @example.prod @example.dev.livedev --label=vcs
    
  3. Commit the configuration on the Development environment:

    drush @example.dev.livedev ssh git commit -am "Copy config from Prod."
    
  4. Import the copied configuration into the Development environment:

    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 develop a Drupal 9 application in a local environment, note the following:

  • Download the Acquia Cloud Platform Drush integration 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

Acquia Cloud Platform defines a vcs configuration directory type in addition to the sync configuration directory type for configuration. The vcs directory is unknown to Drupal core and most contributed config modules, such as Config_split.

Acquia recommends that you set the vcs and sync directories to be the same in the settings.php file, as follows:

$config_directories['sync'] = $config_directories['vcs'];
$settings['config_sync_directory'] = $settings['config_vcs_directory'];

Protecting configuration in the Production environment

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