Setup Config Ignore and Config Split
The best practice for managing Site Studio configuration is to use Config Ignore and Config Split to remove Site Studio configuration from Drupal core configuration export and import process. See below for a brief explanation about the these terms.
Site Studio Module Configuration
Site Studio follows standard Drupal community contributed module conventions and stores various module settings in Drupal config entities. This covers configuration required for basic functionality of the Site Studio module such as account, system, google maps API, element and package export settings. This type of configuration is stored using cohesion.* naming pattern. Examples of such configuration include:
Site Studio Configuration
Configuration entities related to the theme layer of the project - styles, templates, components, etc. This type of configuration is stored using cohesion_* naming pattern. Examples of such configuration include:
Contrib module that provides base functionality for hooking into Drupal configuration import and export processes
Contrib module built using Config Filter. Its main purpose is to ignore specific configuration during the configuration import process.
Contrib module built using Config Filter. Its main purpose is to set up a specific configuration to be split up from the rest of the configuration export. Split configuration can be handled in multiple ways:
- Placed in a separate configuration collection, but still exported with the configuration export process
- Placed in its own directory, but still exported with the configuration export
- Placed in database - export process will leave configuration in the database and will not create any files in the filesystem that are deemed to be part of the “split off configuration”
This guide is based on Drupal Configuration management best practices and recommends the use of the contributed module Config Split (config_split) and Site Studio Packages. The guide covers managing Site Studio Configuration for configuration entities related to the theme layer of the project (cohesion_*). If your project uses alternative or incompatible strategies to manage configuration then you must apply this principle to your application.
This guide does not cover Site Studio Module Configuration (cohesion.*) - handling generic module configuration will depend on project requirements and should be handled in the same way as the rest of your Drupal configuration.
We also recommend that the Site Studio API and Organisation keys are excluded from your codebase, see information on Storing sensitive information outside of your codebase (https://docs.acquia.com/resource/secrets/).
Here are the steps to configure the Config Ignore and Config Split modules to remove Site Studio configuration from the Drupal configuration export and import process:
- Download and enable Config Filter (config_filter), Config Split (config_split) and Config Ignore (config_ignore) contrib modules.
- Enable Site Studio Sync (cohesion_sync).
- Configure Config Ignore to ignore Site Studio configuration during Drupal configuration imports by adding the following Configuration name pattern (/admin/config/development/configuration/ignore):
- Add new configuration split to Config Split module (/admin/config/development/configuration/config-split). Name of the config split can be anything, but we recommend something self-explanatory like “Site Studio” (site_studio)
- Configure your newly added configuration split to separate Site Studio configuration from the rest of Drupal configuration during exports by adding the following settings:
- “Storage” should be selected to “database”. This will ensure configuration exports are not recreating Site Studio configuration in the filesystem, which should lead to much more manageable version control workflows and work reviews.
- “Status” should be set to “Active”.
- In the “Complete Split” section leave all of the checkboxes empty, but add the following line into “Additional Configuration”:
- Leave the “Partial Split” section with default settings - no options should be selected and the “Additional Configuration” text box should be empty
- Leave the “Advanced” section with default settings - “Stackable” option should be left unchecked
- Save your configuration split settings.
Validating your configuration changes
Validate that the changes take effect during Drupal core configuration export and import and test as part of your configuration management developer workflow:
- No cohesion_* entities are imported or exported to your configuration directories as part of any configuration tasks.
- cohesion.settings will be exported to your configuration directory.
- cohesion.sync.settings will be exported to your configuration directory if you intend to use and have configured full export settings.
- Site Studio API and Organisation keys are not exported, overwritten or imported.
If these occur please revisit the setup steps or check if there are any conflicts with your existing configuration management strategy.