Drupal 8 – Manage your Configurations per Environment

Through this Blog, I would like to address the challenges we face using the core Configuration Manager. We are all familiar with importing, exporting and synchronizing a site’s configuration components using drush, composer & git to maintain a consistent configuration across different development environments. A basic example workflow would involve the following steps:

Site A

  • $ composer require drupal/devel
    $ drush en -y devel
    $ drush cex
    $ git add . && git commit -m "message"
    $ git push

Site B

  • $ git pull
    $ drush cim

Now, the above workflow works perfectly as long as we desire all environments to have the same configuration. But, what if we wanted some differences in configurations for different environments? Say, for instance, you want to install the Devel module on your Local & Development environment but want to keep it uninstalled on the Stage & Production sites. How will you achieve this?

Another situation might be that you want to enable the Core Database Logging module on your development server to make accessing error logging quick and easy for developers, but disabling that module on your Production site since logging messages to the database has performance implications.

Out of the Box, there is no such smooth, automated process in the core that takes care of the above 2 situations.

Enter the Drupal Community contributed module,  Configuration Split. This is a Drupal 8 module that provides a way to segregate configuration components so that you can isolate them for different environments.  In short, we can have different sets of configurations, settings & modules for different environments.

Now, since this module seems to address the challenges we are facing with the core configuration manager, so let’s check it out.

In our local development environment:

  1. Install the module
    $ composer require drupal/config_split
    $ drush en -y config_split
  2. Ensure that you have changed the location of your config folder from inside the default sites/default/files directory to a new directory outside the Drupal docroot so that it is in the location as shown below:
    |--docroot (drupal web root)
       |--sync (configuration export storage)
  3.  Next, uncomment the following lines from your settings.php file:
    # if (file_exists($app_root . '/' . $site_path . '/settings.local.php')) {
    #   include $app_root . '/' . $site_path . '/settings.local.php';
    # }

    So, we will be using the settings.local.php file to store settings configuration for each environment. Usually, this file would be created in the same location as the settings.php file (sites/default/files).

  4. Now, for the magic to start, insert the following lines above the uncommented lines of your settings.php file:
    ## Disable split config settings
    $config['config_split.config_split.local_dev']['status'] = FALSE;
  5. Next, configure your site for the Production environment. We will take the above mentioned use-case and uninstall the modules – Devel, Views UI, Field UI, etc. Export these config changes:
    $ drush cex
  6. Next, for the actual splitting to take effect, add a second directory inside your config directory, making sure it is writable by the web user. This new directory will store your development environment specific configuration.
    docroot (drupal web root)
       -sync (configuration export storage for production)
       -local_dev (configuration export storage for local development)
  7. Now, in our local settings file – settings.local.php – that contains our development environment specific settings, add the following lines:
    ## Enable split config settings
    $config['config_split.config_split.local_dev']['status'] = TRUE;

    The above setting will override the setting added in the main settings.php file. Hence, this will actually enable a split configuration management for our local development environment.

  8. Now, we are ready for making the environment specific module settings.
  9. First, we will need to create a development configuration profile by visiting /admin/config/development/configuration/config-split and click on the Add button.
  10.  Name your Configuration Split profile according to your environment. E.g., Local Dev. Add the location of your development configuration directory, relative to the Drupal docroot, and check the “Active” checkbox:
  11. Scroll down to select the modules whose settings you want to split or which are specific to your local development environment.

    Once you have selected all the  modules for local development only, you can save the profile.
  12. Next, we need to export our development configuration. The Configuration Split module introduces two new drush commands:
    $ drush configuration-split-export (csex)
    $ drush configuration-split-import (csim)

    These two commands specifically import and export your local development configuration settings.

  13. To export your development environment configuration, execute:
    $ drush csex local_dev -y (or the machine name of your local development configuration)
  14. The Core config-export command will now export both your production configuration settings and your development configuration settings, isolating them to the configured sub-directories within your config directory.
    $ drush cex
  15. You may or may not need to add your local development configuration directory to version control depending on your use-case.


So, in this way described above, we can keep development related modules installed on our local and development environments while keeping the production environment clean of these modules.

You can create more directories  per configuration profile depending on your use-case. I have only demonstrated a very basic use-case in this blog.

The settings added in Point#4 will disable the configuration split between the sync directory and the local_dev directory, and executing drush cim on your production server will ignore the configuration files in your local_dev directory. Which means  that any continuous integration scripting process that you may have in place that imports configuration files should still work just fine for your production environment.

About The Author