Moving configuration in D8

Drupal 8 has a new core module called Configuration Manager. It allows you to get site configuration, which is usually stored in the database, add give you the capability to migrate between environments and commit them to version control systems.

This is a little like Features but there are some distinct differences, the main ones being:

Configuration Manager

In core Exports the entire site^[2] Saves configuration as YAML files Configuration can only be applied to the same site^[3][4]

Features

Contrib module(s)^[1] Exports groups of elements Saves configuration as PHP Features can be moved between sites

^[1] Features cannot export everything. Eg Strongarm is required for system variables.
^[2] It is possible to export / import single yml files.
^[3] To be the “same site” they must have the same UUID. This means that they have the same settings.php file and initial database content.
^[4] Settings can be migrated to different installs but it is trickier.

Configuration Location

In your sites/default/files directory there will be a directory with a name like:
config_ThisIsARealyLongStringOfUpperAndLowerCaseAlphaNumericCharactersWith-And_

Inside this, there are active and staging folders.

DO NOT CHANGE ANY FILES IN ACTIVE. IT CAN BREAK YOUR SITE.

Staging is where new / altered configuration files can be placed.

Exporting

Before importing a configuration, you need to export it.

The easiest method is to do a Full Export. To do this, go to /admin/config/development/configuration
Configuration -> Development -> Configuration management

If you get a “Page not found”, Configuration Manager is not enabled. Enable it through Extend (/admin/modules).

And select the “Full Import/Export” tab, then “Export”. Finally click the “Export” button. This will start to download the configuration archive.

If you want you can uncompress this file and have a look inside. I found 172 YAML files - and that was from a standard installation with no further setup.

Importing

Importing much the same as exporting. You go to /admin/config/development/configuration

Configuration -> Development -> Configuration management

And, again, select “Full Import/Export”. You should be on the import screen, if not click “Import”.

Next click “Choose File” and find your config.tar.gz file. Then upload it.

This un-compresses the file and puts all the yaml files into the sites/default/files/config_*/staging directory and they are ready to move the settings into the database.

Synchronize

Synchronizing reads the config files that have been imported and makes the database match these settings.

The “Synchronize” page is the default screen of the Configuration manager. If you have already done some exporting or importing, then select the relevant tab.

If you haven’t imported a config file yet or the import matches the database, you will see a message telling you that:
“There are no configuration changes to import.”

If there are differences, then you will be shown a list of new, changed, and removed files. You can have a look to see what has changed. The settings in the database are under “Old” and the config file settings are under “New”.

When you’ve finished looking at the changes, clicking “Import All” will make the database match the settings in the files - there is a progress bar to let you know how far through it is.

Version Control

You can use Configuration management to store database settings in version control. You would export config and then import it into the same site - to check it’s done properly, check synchronize to make sure there are no differences.

As most developers would exclude the files directory you would need to re-include the config_* files.

In your .gitignore file (for example) you would have:
sites/default/files/*
!sites/default/files/config_*
sites/default/files/config_*/active

The second line re-adds the config yaml files to the repository, and the third excludes the active directory again - as noted before:
DO NOT CHANGE ANY FILES IN ACTIVE. IT CAN BREAK YOUR SITE.

Conclusion

I would recommend using Configuration manager during development because:

1. it gives the ability to revert database settings to previous settings;
2. it allows you to store database setting in version control;
3. you can update a live site from development easily;

Also, it’s easier to use than features; export, import, synchronize. And only takes a couple of minutes to do.