Last updated March 31, 2014. Created by heyrocker on October 26, 2012.
Edited by Pedro Lozano, Michael Hodge Jr, Gábor Hojtsy, aschiwi. Log in to edit this page.

Drupal 8 has a whole new configuration system that uses human-readable text files in the YAML (.yml) format to store configuration items. All of your site configuration from enabled modules through fields, contact categories to views are stored with this system. The system is designed to make it much easier than prior Drupal versions to export all your site configuration, make changes and import changes back in.

The Configuration Manager module in Drupal 8 provides a user interface for importing and exporting configuration changes between a Drupal installation in different environments, such as Development, Staging and Production, so you can make and verify your changes with a comfortable distance from your live environment.

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) located in the system.site.yml file. The site UUID must match the target site to allow any importing of configuration files on that site.

This capability replaces the need for various contributed modules such as Features and Strongarm.

Configuration files

Drupal 8 uses the YAML (.yml) human-readable text file format to store configuration. Default configuration shipped with modules, distributions and themes is stored with the projects themselves in a config subdirectory. These default configurations are imported into the active configuration store when the respective projects are enabled. So the active configuration store is the complete set of live configuration at any given time.

The active configuration files can be found by default at sites/default/files/config_XXXX/active (where XXXX is a hash that looks somewhat like iND62oxf-4DyUHcbCA7mhupb_KEpUaGZ6qcfTnAscNQ). There is also a staging directory on the same level, that Drupal uses to stage configuration changes. It will be empty by default and only populated when in the process of importing configuration.

An illustration of this process on your development site looks like the following:

Defining location of configuration folders

During the installation Drupal writes the location of the (active & staging) configuration directories to the settings.php file.

<?php
$config_directories
['active'] = 'sites/default/files/config_iND62oxf-4DyUHcbCA7mhupb_KEpUaGZ6qcfTnAscNQ/active';
$config_directories['staging'] = 'sites/default/files/config_iND62oxf-4DyUHcbCA7mhupb_KEpUaGZ6qcfTnAscNQ/staging';
?>

By default these folders are relative to the Drupal root installation folder.

You can override these locations in the same settings.php file.

<?php
$config_directories
= array(
 
CONFIG_ACTIVE_DIRECTORY => '/var/www/d8/config/active', // outside the webroot
 
CONFIG_STAGING_DIRECTORY => '/var/www/d8/config/staging', // outside the webroot
);
?>

The configuration files are "hidden" by way of the random hash in the directory name and a .htaccess file in the active and staging directories containing the directive Deny from all to stop your webserver from serving them. Moving the directories outside of the webserver root is possible for further security.

Importing, exporting, and synchronizing configuration

Making configuration changes on the live site is often not the best idea. The goal of the configuration system in Drupal 8 is to make taking a copy of the site configuration easy to set up a development site where you make changes. Then importing those changes on the live site is also made simple.

You can import, export, and synchronize configuration in your site via Manage > Configuration > Development > Configuration management (admin/config/development/configuration).

It is possible to export a single configuration file and paste it into another environment. The single import otion lets you specify the type of the configuration file and import it from your copy-pasted value.

The full export feature is a lot more powerful. You can download the an archive of all the active configuration files with this feature. This can be used to import on a development site (given the two sites are copies of each other) to import, synchronize, make changes, package up again and import and synchronize back on the live site as well.

Assume you have identical dev and prod sites. Any changes made on the dev site will be saved into the active storage on the dev site. This can be exported and imported on the live site. The import will copy the YAML files into the staging directory.

Once you ran the import, you should synchronize your changes which will let you review all the changes between the prod active and staging directories.

From this list you can view the differences between each of the config files to ensure that the changes are as expected, before setting the changes active.

The Synchronize page will also show new or removed config files. It is important to check that there are no removals of any core config files (such as system.*, entity.*) as this will result in a site error.

Once the Synchronization is ran, the staging directory contents are now elevated to the live configuration, new modules are enabled, new fields, content types, etc. are added. In short all changes are live.


Examples

Workflow using the Drupal UI

Here is a simple example that demonstrates how the site name can be configured in one environment and then deployed to another environment.

  1. Install Drupal 8. We will call this site "Live."
  2. Make a copy of this site (We'll call this "Development"). Make the copy by using the same source code, the files directory and a database dump of the Live site imported on Development. With Drupal 7 you would have only needed the database dump and uploaded files, in Drupal 8, other parts of the file directory are relevant, including the configuration and PHP files. A full copy of the site will do.
    Note that once #1613424: Allow a site to be installed from existing configuration will be done, it would be possible to install a fresh site from existing configuration, so copying the site would be as easy as installing a new site with the configuration exported. Until that is fixed, you need a full copy of the site.
  3. On the Development site, change the site name in admin/config/system/site-information
  4. Export the full Development site configuration at admin/config/development/configuration/full/export. This will create a compressed file.
  5. On the Live site, navigate to admin/config/development/configuration/full/import and upload the compressed file. After upload, review the changes and click Import all

Now your site name is changed on the live site as well. Although theoretically you should make all changes on Development and deploy to Live, sometimes changes on Live directly may be necessary. To take those changes from the Live site to Development, do the following:

  1. Export the full Live site configuration at admin/config/development/configuration/full/export. This will create a compressed file.
  2. On the Development site, navigate to admin/config/development/configuration/full/import and upload the compressed file. After upload, review the changes and click Import all

This will update the Development site with any Live changes. From here, you can continue making further changes on Development and import back to Live when you are happy with the changes.

File system based workflow

  • Copy the configuration (.yml) files from the origin website's active folder to the origin website's staging folder.
  • Use a tool (rsync, git, ftp, scp) to copy the content of the origin's staging folder to the destination's staging folder
  • In the destination website visit admin/config/development/configuration
  • Click import all

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.

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.