Config Suite
A set of improvements to Drupal's configuration management system that removes the Site UUID check and provides automatic import/export functionality.
config_suite
Install
composer require 'drupal/config_suite:^2.0'
Overview
Config Suite enhances Drupal's core configuration management system to make it easier to work with configuration in a version-controlled workflow. The module addresses common pain points when sharing or reusing configuration between different Drupal sites.
The primary feature removes the Site UUID validation during configuration import, which normally prevents importing configuration from a different Drupal installation. This eliminates the error "Site UUID in source storage does not match the target storage" and allows developers working on different copies of the same site to share configuration without workarounds.
Additionally, Config Suite provides automation features that can automatically export configuration changes to the sync folder whenever a form is saved, and automatically import pending configuration changes when an administrator accesses the site. These features streamline the configuration workflow in development environments.
Features
- Bypasses Site UUID validation during configuration import, allowing configuration to be shared between different Drupal installations
- Automatic configuration export to the sync folder when any configuration form is saved
- Automatic configuration import when administrators access the site and the sync folder has been updated
- Exports all active configuration to the sync folder upon module installation
- Supports configuration collections for comprehensive configuration synchronization
Use Cases
Multi-developer team workflow
When multiple developers work on the same Drupal project with separate local installations, each site has a different UUID. Without Config Suite, importing configuration from a colleague's work would fail with the UUID mismatch error. Config Suite allows developers to freely share configuration files through version control without UUID conflicts.
Site migration or cloning
When creating a new site based on configuration from an existing site, or when migrating configuration between staging/production environments with different UUIDs, Config Suite allows the configuration to be imported without manual UUID manipulation or workarounds.
Automated development workflow
Enable both automatic import and export to create a seamless development experience. When you make configuration changes through the UI, they're automatically written to the sync folder for immediate commit to version control. When a colleague's configuration changes are pulled from the repository, they're automatically applied on your next page load.
Configuration reuse across projects
Create reusable configuration snippets that can be applied to any Drupal site regardless of its UUID. This is particularly useful for agencies or developers who maintain similar configurations across multiple client sites.
Tips
- Config Suite is particularly useful during development but consider disabling automatic features in production environments where configuration changes should be more controlled.
- The automatic import feature only runs for users with the administrator role for security reasons.
- Upon module installation, all active configuration is exported to the sync folder, ensuring you start with a complete configuration baseline.
- A video introduction to Config Suite is available from BadCamp: https://www.youtube.com/watch?time_continue=112&v=02IJGgGPBAw
Technical Details
Admin Pages 1
/admin/config/config_suite/admin_settings
Configure automatic configuration import and export settings for Config Suite. This page allows you to enable or disable automatic synchronization of configuration between the active storage and the sync folder.
Permissions 1
Hooks 2
hook_install
Exports all active configuration to the sync folder upon module installation, ensuring the sync folder is immediately populated with current configuration.
hook_help
Provides help text for the module on the help page.
Troubleshooting 3
Ensure the automatic import setting is enabled, and that the logged-in user has the 'administrator' role. The automatic import only triggers for administrator users.
Verify that automatic export is enabled in Config Suite settings. Also ensure that the sync folder is writable by the web server.
These warnings may appear in logs when configuration collections don't contain the specific configuration item being saved. This is usually harmless and indicates the configuration doesn't exist in that particular collection.
Security Notes 3
- The automatic import feature only executes for users with the administrator role, preventing unauthorized configuration changes.
- This module bypasses the Site UUID check which is a security feature in core Drupal. While convenient for development, understand that this removes a safeguard designed to prevent accidental configuration overwrites between different sites.
- Consider the security implications before enabling this module on production sites, as automatic configuration import could potentially be exploited if an attacker gains write access to the sync folder.