Drupal configuration management

Overview

All configuration should be exported to disk via configuration synchronisation and managed through unless site editors will need to change the configuration via the UI.

Where site editors will need to make changes to site configuration, this configuration should be split out using the Config Split module.

In some case different environments will need different settings. The preferred way to do this is to use configuration overrides, but for complex environment specific configuration, Config Split can be used.

If there's no need for Config Split to be used (for example a simple site where there's no requirement for site editors to make changes to configuration), then the config_exclude_modules setting should be used to ignore config for development modules like Devel and Stage File Proxy.

Configuration overrides

For many sites there are going to configuration settings that need to be different for each environment. An easy way to change specific configuration for a specific Drupal installation is to add a configuration override to the site's settings.local.php. This changes the value of a configuration item then is held in the database and git to that defined in the file and is ignored when importing or exporting configuration.

For more information on configuration overrides see: https://www.drupal.org/docs/drupal-apis/configuration-api/configuration-override-system

Example Solr config override

This is useful when defining Solr server and core settings when the Search API Solr module is used. The local Lando settings will have a different server host, while the production and stage environments will likely have different cores.

These will be different for the dev, stage and production environments.

The following assumes there's a single Solr server defined called solr with a core named solr in Lando, site_stage for stage and site_prod for production.

For the local dev environment, add the following to the site's settings.lando.php or settings.local.php.

$config['search_api.server.solr'] = [
  'backend_config' => [
    'connector_config' => [
      'host' => 'solr',
      'path' => '/',
      'core' => 'solr',
      'port' => '8983',
    ],
  ],
];

For stage add to settings.local.php:

$config['search_api.server.solr'] = [
  'backend_config' => [
    'connector_config' => [
      'host' => '127.0.0.1',
      'path' => '/',
      'core' => 'site_stage',
      'port' => '8983',
    ],
  ],
];

And for production add:

$config['search_api.server.solr'] = [
  'backend_config' => [
    'connector_config' => [
      'host' => '127.0.0.1',
      'path' => '/',
      'core' => 'site_prod',
      'port' => '8983',
    ],
  ],
];

Configuration Split

Config overrides are good to small changes, but there are often many changes between different sites and these are best handled with Config Split. This splits configuration out from the main configuration sync directory into it's own directory or stored in the database. Splits can then be enabled or disabled for different environments using a config override.

Further help on Config Split can be found at:

Creating a split

  1. You should not be overriding the status of any split locally, via your settings.php, when creating a split.
  2. Ensure that your default export, i.e. the config exported to config/split, is appropriate for local development.
  3. Update the configuration, usually via the UI, with the settings appropriate for the environment you want to make the split for.
  4. Create the directory for the new split, typically this would be adjacent to the default config directory i.e. config/prod.
  5. Create a new split choosing the relevant Configuration items - typically a Conditional split would be used. Enter the path to the newly created directory relative to the web root in Folder, i.e. ../config/prod.
  6. Set the status of the new split to Active.
  7. Export your config. You should see some new files in the split directory, i.e. config/prod, which correspond to the split configuration.
  8. Now the awkward bit: the previous export will have exported the config for the split itself which includes it's enabled status, this is not really what we want as we'll be controlling the status via setting.php so the easiest thing to do here is manually edit the value of status within the split's config export to be false, i.e. config/sync/config_split.config_split.prod.yml, and disable the split via the UI.
  9. Finally, set up the environment to use your new split. If we created a split with a machine name of prod then the following line would be entered into the settings.local.php on the production environment:
$config['config_split.config_split.prod']['status'] = FALSE;

An example of creating a development split can be found on drupal.org: https://www.drupal.org/docs/contributed-modules/configuration-split/creating-a-simple-split-configuration-dev-modules-only-in-dev-environments

Importing a remote environment's DB to your development environment

When using Config Split some care is required to ensure the default configuration is not overwritten when importing DB to your development environment.

If you're importing the Production DB and prod is using a split then after importing the DB to your development environment ensure you run a config import before performing any export - it's best to do this before you start any development otherwise you could lose you local configuration changes - this is because the imported DB will contain the split settings so an export will overwrite the default settings with the prod settings.

Ignoring configuration from export\import

Sometimes you'll want to exclude certain configuration completely from export\import and git. Examples include:

This can be done by using Config Split to store the changes in the database and not export them into configuration at all.

This can be done by:

  1. Create a new split, i.e. 'Ignored config'.
  2. Choose the configuration items you wish not to be exported - typically we'd use a Complete split here.
  3. Ensure the Folder field is empty.
  4. Set the weight to: -10.
  5. Ensure the status is Active.
  6. Export your new split.

Excluding module configuration with config_exclude_modules

For simple sites there maybe no need for Config Split, but we will still want to exclude config for development modules being exported and ending up on production. For example, having Stage File Proxy enabled and configured on the production site is VERY BAD; it can take the website offline by causing infinite redirects as it requests images, that request an image, that requests an image, etc. until all the web server processes are used up.

In this situation the config_exclude_modules setting can be set to ignore the configuration for development modules and ensure they never end up enabled on production.

To do this add the following to the site's settings.php file to ensure the config is excluded from all environments.

$settings['config_exclude_modules'] = ['devel', 'stage_file_proxy'];

More information can be found on the drupal.prg change record for this https://www.drupal.org/node/3079028

Last updated: