Blog

The introduction of the configuration system in Drupal 8 can greatly minimize site deployment time and effort yet can cause excessive grief if it is not managed properly. Without trying to rewrite existing documentation already in existence, this will point out some key issues and general guidelines for making the most of it.

This requires Drush and a fully functioning Drupal 8 site with full access to the server(s). You should also have a remote repository set up with separate environments to test multiple developer workflows.

See https://www.drupal.org/docs/8/configuration-management/managing-your-sites-configuration for detailed ‘official’ documentation on using the configuration system.

For the bulk of Drupal developers, we are used to three main components. Database, Code and Files. The ‘Files’ being images, uploads, etc. and are of course, not version controlled and for the most part ‘static’. The ‘Code’ is generally version controlled and is the main component that is updated during a website deployment or update. The ‘Database’ (otherwise known as the ‘configuration’) of the site has never really had a form of ‘version control’ which would make site updates and deployments more automated. Sometimes this is not obvious to novice users as it’s often overlooked that site content lives in the same system where configuration is stored. In other words, all configuration was manual unless a module such as ‘Features’ was used, which could get quite messy as a site matured.

Before diving into the basics, there are of course plenty of modules and tools that can customize configuration based workflow. Until a solid understanding of how the system behaves, it may be best to leave these other tools out of the picture.

What makes up site configuration?
While custom and contributed modules can make this list endless, some basic items that are part of a Drupal site’s configuration are:

• Content Types
• Taxonomy Vocabularies
• Block configuration (e.g. block placement settings)
• Field definition and storage
• Core site settings (e.g. Site name, cache settings, text formats, etc.)
• Theme settings

A basic workflow for site updates for configuration

You have a site on a live hosting server with a lot of traffic and need to add a content type with some fields, a view and place a block on the homepage. While this may seem simple enough to complete this on the live environment without much risk, you want to make sure there is adequate testing done on a staging or development environment.

Prepare for configuration usage:

• Assuming no other work is in process, you will pull a current copy of the Database, Files and Code into your local development environment.
• By default the configuration system is not version controlled. It is usually kept in the public directory which has some general security concerns and quite honestly, you may not want someone randomly looking at how your entire site is constructed.
• It is recommended to move your configuration into a directory that is not publicly accessible yet still within the version controlled directory. Usually one directory up from the document root. There is documentation on how to do this here https://www.drupal.org/docs/8/configuration-management/changing-the-storage-location-of-the-sync-directory . You can also set up multiple configuration directories for multisites.
• Once your local environment is setup and functioning as a mirror of your production site, you will need to export the working configuration. The drush command ‘drush config-export’ is best suited for this. (Do this on your development environment).
• Before making any changes, you should perform a ‘zero change’ update to a staging environment and ideally back into the production environment.
• Assuming the configuration has been exported, you will commit all file changes to the repository and push to the remote environment. If possible, use the remote shell to run the drush command ‘drush config-import’ . Assuming you pulled the most current database for your site, there should be no major changes being applied. You may see an update to the system.settings. Once the import is run, double check the site and run update.php to ensure everything is synced.
• Test application of change:

• Before making too many changes and until the configuration system is well understood on the site, it will benefit to see one small change make its way through the entire workflow.
• On your development site, make one change that will be a part of your entire update. For example, add a content type.
• Once the content type is made, run ‘drush config-export’ on the development site. You should see a list of configuration files that are changing since adding the content type. The status on the file(s) should only say ‘update’ or ‘create’. If all looks well, enter ‘Y’ to export.
• Now you will see those files needing to be committed into your version control repository. Add, commit and push those updated files.
• Once pushed to the remote, run ‘drush config-import’ on the remote environment. You should see the same files appear in a list asking you to confirm the changes. You should not see any file status of ‘Delete’ (unless of course you removed something through configuration)
• On the remote environment, you should see the new content type as it was exactly set up on your local environment.
• Make all changes and push to production

• Now that the environments are in sync, you can now complete all work on your development environment.
• When all work is complete, export the config (drush config-export) and push those files changes to your remote environment.
• Importing the config (drush config-import) on your staging environment should apply without conflict as long as there are no other changes being made directly on the staging environment.
• To move these changes to production, you will move the version controlled code base to your production environment. (via tags or merging into a production branch).
• Assuming the ‘zero change’ update to production was completed without incident, you should be able to run ‘drush config-import’ on the production environment and you will see the updates being applied. BACKUP THE DATABASE BEFORE COMPLETING THIS STEP!

Working with multiple developers/branches

• The configuration system does not play well with multiple ‘versions’ and is extremely finicky when it comes to merging changes without very strict management of development.
• If possible as site configuration is being updated, it is best to handle one release at a time. As one developer makes a change, exports then pushed to remote, another developer should see the requirement to pull those changes. If any configuration files are updated in the pull, that developer should then import changes into their development environment, re-export, push all changes back then import all changes on remote.

Notes about configuration and overriding of settings and/or content

• Configuration is meant for one site. Based on UUID. You cannot import configuration into a site from another site to ‘copy’ the site.
• Configuration can have module dependencies so be sure to include any code updates as needed when updating configuration.
• If you make configuration changes on the remote environment (e.g. permissions, field settings, etc.), those changes will be overridden unless the exact change has also been made on the development environment and exported.
• Configuration (just as manual database updates) should always go upstream. Any downstream synchronization should only be done at the beginning of a development cycle or release.
• Always make a backup before applying any configuration changes.
• If there is content associated with a configuration item and that item is removed, all associated content will be removed as well.
• For example, if a local configuration does not have the ‘Article’ content type, yet the production environment does, when the configuration is pushed up and imported, all articles will be deleted.
• Since configuration files can be ‘recreated’ during any export of a development site, it is extremely difficult to determine the most current version. Therefore version controlling (GIT) may give misleading results when trying to merge to get current configuration