Warning message

Documentation is currently being migrated into the new system. Some pages might be temporarily missing, and some guides might appear empty. Thank you for your patience while we are improving Drupal.org documentation.

Managing your site's configuration

Last updated on
September 9, 2016 - 12:48

Drupal stores all your site's configuration data in a consistent manner. All of your site configuration from the list of enabled modules, through to content types, taxonomy vocabularies, fields, views, and so on, is stored with this system. The system is designed to make it easy to make changes, export site configuration to files, and import those changes back into the site.

The active configuration is stored in the database by default. This is the complete set of live configuration at any given time. The configuration can be exported and imported as YAML files, either for a single piece of configuration, or the entire set of configuration for the site.

Exporting and importing configuration changes between a Drupal installation in different environments, such as Development, Staging and Production, allows you to make and verify your changes with a comfortable distance from your live environment. This can be done with the Configuration Manager module, or with the Drush command line tool.

This allows you to deploy a configuration from one environment to another, provided they are the same site. The site is identified using a Universally Unique Identifier (UUID). The site UUID must match the target site to allow any importing of configuration files on that site.

This can be done in a way that integrates with the version control of your site's codebase and your deployment process.

Installation configuration files

Default configuration shipped with modules, distributions, and themes is imported into the active configuration store when the respective extensions are enabled. An extension's default configuration is in the form of files in its config/install directory.

Importing, exporting, and synchronizing configuration

Making configuration changes on the live site is often not the best idea. The goal of the configuration system to make it easy to take a copy of the site configuration, and set up a development site where you make changes. After changes are made, importing the development configuration back into the live site is also made simple.

With the Configuration Manager module (config) enabled, you can import, export, and synchronize configuration in your site via Manage > Configuration > Development > Configuration Synchronization (admin/config/development/configuration).

Configuration can be synchronized as individual configuration objects with a copy/paste workflow. This is useful if, for example, you wanted to just move a newly created view from one environment to another.

Configuration can also be synchronized as a full export wherein the entire configuration of a site is synchronized between environments.

Synchronizing configuration only works if you're moving configuration between two copies of the same site. Like a developer's copy of the site used for testing new configuration and the live production site where you would like the new changes to appear.

There are a few different ways that you can perform a full configuration synchronization, including:

The configuration manager can also be used to review changes before importing them to ensure the changes are correct.

Once the synchronization is completed, all the changes will be made, such as new modules being enabled, or new fields, content types, etc. being added. In short all configuration changes made on the development site are now live on the production site.

More Information

If you're looking for more in-depth information about the Configuration Management system in Drupal 8, you can check the handbook pages for Configuration API.

Do's and Don'ts

DO'S

  • It's strongly recommended that you do a database-dump before each synchronization of the staging and the active directory. The database-dump "could save your life" on a potential needed rollback-strategy.

DON'TS

  • Try to change the active configuration on your site by changing files in a module's config/install directory. This will NOT work because Drupal will only read from that directory when the module is installed.