We’ve been building Drupal 8 sites for production since 2016. Over the years we’ve worked through a wide variety of challenges. One challenge we recently encountered was utilizing configuration management on a complex multi-site setup. There are a number of good articles out there detailing how to use configuration management. However, we found that most of these covered an optimal scenario and fell short of our needs for a complex setup. And while there’s a lot to love about Drupal’s configuration management, there are also a lot of pitfalls. We’d like to give a comprehensive overview of what worked well and what didn’t for us.
Benefits
If you’re new to Drupal 8 or have never used configuration management before, here’s what you need to know. Configuration management lets you sync your site configuration across environments. For example, if you are working on a new content type in your dev or local environment, you can simply export the configuration when you have completed it and import it into your live environment. This allows you to safely do all your development and testing in one environment and sync your changes in another, with a guarantee that it will have the same setup and configuration. That’s peace of mind. There’s no second guessing that the live site is missing parts of the feature you developed. It just works.
Pain Points
That said, this isn’t a silver bullet. Consider your options. Even for a general use case there is a big effort involved to make configuration management work. You need to have complete buy-in from the entire team on a workflow and stick to it. If you wander off that workflow you could find your site completely out of sync with your other environments. As Dries pointed out in his article there are a number of shortcomings with the current core configuration management system. Environment specific configuration is a pain point, but there is a good contrib module, config split, to solve that. Multi-site takes that to another level because now you’re dealing with 3 or 4 config splits for each site in your project. Finally, another big challenge is dealing with dev or stage site configuration changes. Ideally, you would never have to make configuration changes on your hosting environment, but we’ll get into why that happens later on (Acquia Search).
Our Solution
Basic Setup
Let’s start with the basics. We highly recommend using drush to manage configuration. You should also store configuration in version control, outside of your web directory root. Install config split and config ignore. We’ll detail configuring these below.
Version Control
In addition to simply storing your configuration in version control, you need to have a sensible git workflow. Your main development branch, let’s assume it’s master, is the source of truth. It will continue to receive configuration management updates. If your git workflow does not adequately support regular merges with master, your configuration management is sitting on a house of cards. It’s critical that every developer has a good understanding of git, your workflow, and how to resolve conflicts. Yes conflicts will arrive, you can count on that. We found that a very simple feature branch pattern worked well for us.
- Checkout master and pull.
- Create a new feature branch from master. I.e.
new_content_type - Sync configuration on your local/dev environment.
drush config:import (drush cim). - Develop new feature, export config —
drush config:export (drush cex)— and push code. - Merge branch into master, assuming no conflicts. If there are conflicts, see our approach below in Overcoming Obstacles.
Of course, if you have code reviews, pull requests, or other processes to follow in your workflow, insert those in the appropriate place. The important thing to remember is to merge feature branches back into master often. If you have a process that’s more convoluted you're in danger of massive configuration management conflicts.
Folder Structure
It’s important to create a folder structure that organizes your configuration code well. Particularly in a multi-site setup where you might end up with 20+ configuration folders. Remember to keep your root folder outside of your web directory. If you have a single-site setup, your structure might look like this:
configdefaultlocaldevproductionwebroot
default is important. This is the configuration that gets shared across all setups. Local, dev, and production in this case, would all share configuration in the default folder. The other folders are environment specific and setup with config split. Now imagine you have 20 sites. Times that by two or three environments per site and you have 60 folders. Time for a different structure.
configdefaultlocaldevmulti-site-1.example.comdefaultproductionmulti-site-2.example.comdefaultproduction…
You could opt for a flat approach instead.
multi-site-1.example.com.defaultmulti-site-1.example.com.production
We found that creating a site specific nested folder was the cleanest approach. Create a plan and stick to it. Once you create a plan it becomes almost impossible to switch approaches.
One thing you’ll notice is that local and dev live at the root instead of within each site. We were able to share those configurations across all multi-site instances. This ended up saving a lot of work.
Config Split
Config split is essential. While documentation exists, there are a few items that weren’t clear. First off, once you’ve configured your config splits, always set them to inactive. Activate them in settings via config overrides.
Before:
<?php
$config['config_split.config_split.dev']['status'] = TRUE;
After:
This allows you to control which splits are active in code conditionally. Thus, if you are in production, activate the production config. If you are on a specific multisite instance, activate that split. If you need multiple, activate as many as you need. This bypasses a potential problem of database syncing.
Another item we found that isn’t clear, is installing a config split on another Drupal install for the first time. Whether it’s another developer’s instance or the live site you’ll run into this with any new config split. Because the config split is itself a configuration you need to run drush cim twice. The first time it will install the config split. The second time, now that the config split has been installed, it will sync configuration dependent on that split.
Setting up a config split is rather straightforward. There is the concept of complete splits and conditional splits.
Overcoming Obstacles
Configuration management is great, until it isn’t. As mentioned above, there are pain points, and you’ll likely run into them as your project progresses.
Conflicts
If there is only one team member working on your project, you can probably skip this section. However, as your team grows conflicts will begin to arise. And they can be challenging to resolve. Develop strategies to minimize conflicts. Have developers work on specific features that don’t cross into other areas of configuration management that another team member is developing. This can be tricky. Imagine developer A extending the article content type by adding a new field with the machine name field_a. Now imagine developer B creating a new content type and he adds a field with the same machine name field_a. The configuration exported will share the same file name but will likely have different configuration within the file, or at the least, different UUIDs.
Mitigating this type of problem takes practice, planning, and education. Understanding that this can occur is part of the solution. Educate your team about the possible conflicts that can arise. We found that discussing potential configuration conflicts during sprint planning helped cut down significantly on these types of conflicts.
Updates
How do you manage updates? Composer? Drush? Manually? When you update Drupal core and modules, configuration will likely update. It’s important to have a task dedicated to updating and exporting the latest configuration. Imagine the following scenario. Developer A updates modules, but does not export configuration, and their code gets merged into master. Developer B begins working on a new feature and when they are done exports configuration. However they see a bunch of unrelated changes to the work they were doing. They might ignore those changes or commit them. Neither of which is a good solution. Imagine Developer C encounters the same problem and both developers commit the changes. Conflict.
You need to have a process for updates. Not only is it a good rule of thumb, but it will help you cut down on configuration management conflicts.
Working Live
Stop. Ask yourself if you need to work directly on the host (dev/stage/live) environment. Chances are there’s a better way, but sometimes it can’t be avoided. In fact, install and enable the configuration read-only mode module. We found that we needed to work on the dev site to set up solr search. While we had a local solution for solr, it didn’t specifically match the hosting environment setup.
If you find yourself in a similar situation here’s what we recommend.
Communicate. This type of work should be rare and should be the exception, not the rule. Let everyone know when you’re making configuration changes directly on a hosting environment. If you don’t, someone on your team might push up their latest changes, sync config, and wipe out everything you were just working on.
Work in an independent environment. Many hosts these days offer additional environments to the standard dev, stage, and production environments. If they do, perform your work in a separate environment to ensure that your work won’t be overwritten.
Sync your changes to version control. This process will vary depending on your host, but the goal is to get the configuration you just created in version control. There are probably a few options. If you’re on pantheon, you could look into using their custom drush config workflow. If you have drush and version control access on your host you can export and commit directly from your host. We didn’t have these options so we ended up taking a backup of the database locally and syncing the configuration on our local environment. Note, if you go this route there are some pitfalls to avoid. When you take a backup from your host environment it will have one or more config splits enabled that shouldn’t be enabled locally. Thus, if you simply import the new database and export the config, you’ll end up with a bunch of changes that shouldn’t have been exported. This can be easy to miss and will be a pain to revert once it’s been pushed. Instead, update your settings.php config split settings to match the host. Then drush export will update the proper configuration.
Conclusion
Drupal configuration management is a powerful tool. We would definitely recommend using it. Beware of the pitfalls and understand that it will take hard work to make use of its benefits. On its own, each piece of the configuration management puzzle is rather straightforward. However, as your team grows or the complexity of your project changes from a simple site to a complex multi-site setup your configuration management setup could cause you more pain than its worth if you’re not careful. More than anything, a successful configuration management setup is about communication and education. Create a process. Educate your team about the entire workflow from version control to the technical specifics of the config split module.
Research & Design is a design and technology company. We direct our focus to tackling problems within education—working with colleges, universities, and companies serving higher-education institutions—to solve problems through digital communication.
At our core, we are focused on solving problems through clear, concise websites, applications, campaigns, and digital communication. We believe in design as a way of thinking and problem-solving that can be applied to almost any challenge.