How to install Drupal 8 from an existing configuration

The Configuration Management (CM) system, is probably one of the most well known and exciting features of Drupal 8. But wouldn’t it be even more awesome to be able to install a site, export configuration and then re-install site from scratch importing the previously exported configuration?

For those who are not yet clear on what we are talking about, this post is related to fixing the infamous exception error message when importing configuration:

“Site UUID in source storage does not match the target storage.”

Why would you want to be able to install your site from an existing configuration?

A couple of big reasons come to mind:

• Automate the creation of reproducible build/artifacts from scratch at any stage (Development, QA, Production) to test, launch or deploy your site.
• Simplify onboarding for new developers to any project without the need to obtain a database-dump. Developers will be able spin-up sites from scratch just by installing the site and importing configuration files.

How to achieve this using Drupal Console?

Installing a site from a previously exported configuration using Drupal Console is as simple as
updating your console/config.yml and append this configuration to the new overrides section.

application:
...
  overrides:
    config:
      skip-validate-site-uuid: true

Executing the commands to install the site and import your previously exported configuration:

drupal site:install --force --no-interaction
drupal config:import --no-interaction

Simple and easy right? Well, this is possible using Drupal Console starting with the 1.7.0 version. This functionality is not supported by Drupal Core out-of-the-box. However, providing a better user experience while using Drupal 8 is one of the goals of Drupal Console and this is the reason we introduce features as the one we mentioned above.

What if my site does not have Drupal Console installed?

Download Drupal Console using composer in your site. if you do not have it already.

composer require drupal/console:~1.0 --prefer-dist --optimize-autoloader

Create a Drupal Console configuration file for your site.

drupal init --site --no-interaction

What if my site is using an old version of Drupal Console?

Update per-site installation using composer:

composer update drupal/console --with-dependencies

Update the Launcher.

drupal self-update

Can I automate the execution of the site installation and import configuration commands?

Yes, using a chain command. A chain command is a custom command that helps you automate multiple command execution, allowing you to define and read an external YAML file containing the definition name, options, and arguments of multiple commands and execute that list based on the sequence defined in the file.

For more information about chain commands, refer to the Drupal Console documentation.

This is an example of a chain command to install a site and import a previously exported configuration.

command:
  name: build
  description: 'Build site by installing and importing configuration'
commands:
  # Install site
  - command: site:install
    options:
      force: true
    arguments:
      profile: standard
  # Import configurations
  - command: config:import
  # Rebuild cache
  - command: cache:rebuild
    arguments:
        cache: all

After adding this file, you can execute one command

drupal build

If you have any continuous integration or continuous deployment workflow you can integrate this command as part of that workflow.

Will this work with other modules like config_split?

Yes, you can use the config_split provided Drupal Console command. You should use the provided command to import the configuration and it will work as expected, without any issues or errors related to the uuid values.

drupal config_split:import --split=development --no-interaction

Note that you should replace ***development*** with the name you gave to your split.

Do I have other alternatives?

Yes, the other two well-known alternatives are:

Using config_suite module:

• Create a new custom profile.
• Add the drupal/config_suite dependency using composer.
• Add the config_suite module to your custom profile and have it as a dependency on your profile_name.info.yml file.
• Install the site using your new custom profile.
• Export your site’s configuration.

After following these steps, you will be able to reinstall your site using the custom profile and import the previously exported configuration.

Using the config_installer profile:

• Install the site using your preferred contrib or custom profile.
• Remove the install_profile key from your settings.php file.
• Add patches to your composer.json file.
• Add the drupal/config_installer dependency using composer.
• Export your site’s configuration.

After following these steps you will be able to reinstall your site. Note that you will be using the config_installer profile for any subsequent site installation, instead of the profile your site is currently using.

Read more about using config_installer profile:

• Using the Configuration Installer with Lightning.
• Restoring a Drupal 8 site from Configuration Files.
• Installing Drupal 8 from configuration.

Wrapping up

Feel free to update Drupal Console to latest 1.7.0 and try this new feature while is hot and provide feedback. Also, make sure you let us know which other UX/DX improvements you will like to see on the Drupal Console project.