Configuration Management for a Multi-Environment Drupal 8 Development WorkflowDarya SlobodyanikBlockedUnblockFollowFollowingJan 19When I first started working with Drupal 8, one of the first challenges I ran into was configuration management.
Unlike Features, which many of us abused in Drupal 7 as a configuration management tool, there is no option to selectively export configuration to code — it’s all or nothing.
This approach introduces some challenges to a typical development workflow.
Our workflowI’m going to assume your development workflow looks something like mine, which means that you:Use drush to import and export our site configuration.
Commit code to a git repository.
Write code on a local environment, then push it up through one or more remote environments for testing before it finally lands on production.
This gives us two problems to solve:Keeping sensitive data out of our git repoImporting our config files on other environments without overwriting environment-specific variables (maybe our contact form submissions go to a different email address on the test site vs.
the live site, etc).
The official documentation suggests dealing with this by using config overrides, but personally I find that a pain to work with.
Not to mention that:…configuration forms in Drupal Core don’t use the overridden values of the configuration.
With the module override example above, you will not see “Overridden site name!” at /admin/config/system/site-informationPhoto by Igor Rodrigues on UnsplashI don’t even want to imagine how many bug reports that causes.
Luckily there is a better way!A simple configuration management strategyIf your Drupal development workflow involves version control and multiple environments (and if it doesn’t, it should!! but I’m not here to lecture you), I find the best approach as of Drupal 8.
6 is a combination of the Config Split and Config Ignore modules.
Config Splithttps://www.
drupal.
org/project/config_splitWe need to make sure our local variables stay local.
This is where Config Split comes in.
Config Split allows use to define a set of configuration files that get exported to a different directory from the rest of the config files.
When that split is active, config files in that directory override values in the default set.
If you’re not familiar with Config Split, the module documentation is worth a look.
This is great, because this lets us choose what settings we want to commit to code.
The downside of using Config Split alone is that you’re forced to define a separate split for each environment that differs from the main configuration.
I don’t know about you, but that sounds like a lot of work to me, which is why I love to pair this module up with Config Ignore.
Config Ignorehttps://www.
drupal.
org/project/config_ignoreConfig Ignore prevents select values from being overwritten when we import our configuration.
Using this in conjunction with Config Split means that we only need to create one split for our local environment.
Our remote environments will just use the values stored in the database.
Step by stepThis is how I setup every Drupal 8 project.
Pre-setupYour settings.
php file should look something like this:/** * Path to the main configuration directory, outside the * webroot.
*/$config_directories = [ CONFIG_SYNC_DIRECTORY => dirname(DRUPAL_ROOT) .
'/config/default',];/** * Local overrides for settings.
php */$local_settings = __DIR__ .
'/settings.
local.
php';if (file_exists($local_settings)) { include $local_settings;}By default, your configuration files are exported to a folder in your public files directory.
You should always change this, whether you use Config Split or not.
I usually put the config sync directory outside of the Drupal root, but you can move it anywhere that’s not publicly accessible.
After defining my main config directory, I include my settings.
local.
php file.
This is where we'll activate our local config split.
Make sure that the directory you defined exists, and that settings.
local.
php has been added to .
gitignore!Config Split settingsEnable the Config Split module and if you haven’t already done so, run drush cex now.
Create a new split (admin/config/development/configuration/config-split).
I usually name it “Local” which means the path to my local split directory is .
/config/local (based on the location of my main config directory).
Make sure the “Active” checkbox is NOT checked.
Any settings that we plan to ignore on other environments should be added to the graylist.
After you save, activate the split by adding $config['config_split.
config_split.
local']['status'] = TRUE; to your settings.
local.
php file.
Run drush cex to export your current config.
My local split usually looks something like this:If you want to use this as a starting point, just change the theme name and import it.
Before you go on, double check your setup.
Your settings.
local.
php file and your local config directory should have been added to .
gitignore.
Look through the graylisted files in your main config directory to make sure they don’t contain any sensitive data (or anything else you don’t really want committed to code, like the file path to the uploaded logo).
Edit the file and replace any values that you don’t want to export with a dummy value.
Run drush cex again and check that nothing in your main config directory has changed.
Config Ignore settingsTo prevent the empty values from our main config files from overwriting the settings on our other environments, we’ll add them to Config Ignore (/admin/config/development/configuration/ignore).
My list typically looks something like this:some_theme_name.
settingssmtp.
settings:smtp_hostsmtp.
settings:smtp_portsmtp.
settings:smtp_usernamesmtp.
settings:smtp_passwordsystem.
site:namesystem.
site:slogansystem.
site:mailsystem.
site:page.
403system.
site:page.
404system.
site:page.
frontsystem.
performancePro tip: If you add system.
site:name to config ignore, you can add the environment name to the site name on each environment (except production of course).
That way, when you have 62 tabs open in Chrome, you won’t save a form on your local environment, tab to your test environment, and wonder why nothing changed (not that I’ve ever done that before…).
Or accidentally make a change in production (aah!).
Be careful when ignoring entire files.
If you ignore core.
extension you won’t be able to enable modules with config import, and if you ignore system.
site you won’t be able to import anything at all (Drupal needs to be able to read the site UUID).
Done!Now our git repo and our remote environments contain only the configuration settings we choose to export!Hopefully, Config Split and Config Ignore will be helpful in managing your development workflow.
If you have a different strategy for configuration management, let’s talk about it!.