A key component to manage a Drupal website is configuration integrity. A key part of maintaining this integrity is ensuring that your configuration changes that are made in development are pushed upstream to your production environments. Maintaining configuration changes by manually exporting and importing through the user interface can be difficult and does not provide a way to track what has or has not been exported or imported. At the same time, manually writing module hooks to manipulate the configuration can be time consuming. Luckily, the configuration management solution provides you with the ability to export and import the entire site's configuration.
A site export can only be imported into another copy of itself. This allows you to export your local development environment's configuration and bring it to staging or production without modifying the content or the database directly.
In this recipe, we will export the development site's complete configuration entities' definitions. We will then take the exported configuration and import it into the production site. This will simulate a typical deployment of a Drupal site with changes created in development that is ready to be released in production.
You will need a base Drupal site to act as the development site. Another Drupal site, which is a clone of the development site, must be available to act as the production Drupal site.
You will need to get the Configuration management module enabled.
- Visit the Configuration page and go to Configuration synchronization.
- Navigate to the Export tab, and click on the Export button to begin the export and download process:
- Save the
gzipped tarball; this contains an archive of all the site's configuration as YAML. - Visit your other Drupal site and navigate to its Configuration synchronization page.
- Click on the Import tab and then on the Full archive tab. Use the Configuration archive file input, and click on Choose File to select the tarball you just downloaded. Click on Upload to begin the import process.
- You will be taken to the Synchronize tab to review changes to be imported:
- Click on Import all to update the current site's configuration to the items in the archive.
- A batch operation will begin with the import process:
The Configuration synchronization form provides a way to interface with the config database table for your Drupal site. When you visit the Export page and create the tarball, Drupal effectively dumps the contents of the config table. Each row represents a configuration entity and will become its own YAML file. The contents of the YAML file represent its database value.
When you import the tarball, Drupal extracts its content. The files are placed in the available CONFIG_SYNC_DIRECTORY directory. The synchronization page parses the configuration entity YAMLs and provides a difference check against the current site's configuration. Each configuration item can be reviewed, and then all the items can be imported. You cannot choose to selectively import individual items.
When a Drupal site is installed, the UUID is set. This UUID is added to the exported configuration entities and is represented by the uuid key. Drupal uses this key to identify the source of the configuration. Drupal will not synchronize configurations that do not have a matching UUID in their YAML definition.
You can review the site's current UUID value by reviewing the system.site configuration object.
Drupal uses a synchronization folder to hold the configuration YAML files that are to be imported into the current site. This folder is represented by the CONFIG_SYNC_DIRECTORY constant. If you have not defined this in the global $config_directories variable in your site's settings.php, then it will be a randomly named directory in your site's file directory.
Note
When Drupal 8 entered its beta release cycle, this folder was referenced as a staging folder and referenced by the CONFIG_STAGING_DIRECTORY. This is now deprecated; however, the internals of the configuration management system support reading CONFIG_STAGING_DIRECTORY as CONFIG_SYNC_DIRECTORY. This will be removed in Drupal 9.
The synchronization form will use the configuration management discovery service to look for configuration changes to be imported from this folder.
Drupal's configuration management system will not allow the import of configuration entities that originated at a different Drupal site. When a Drupal site is installed, the system.site configuration entity saves a UUID for the current site instance. Only cloned versions of this site's database can accept configuration imports from it.
The configuration installer profile is a custom distribution, which will allow you to import the configuration despite the configuration's site UUID. The profile doesn't actually install itself. When you use the profile, it will provide an interface to upload a configuration export that will then be imported, as shown in the following screenshot:
The distribution can be found at https://www.drupal.org/project/config_installer.