Drupal Best Practices: Using Configuration Management for Scalable Development

Managing a Drupal website requires careful attention to both content and configuration. Whether you’re working with a team of developers or managing multiple environments like local, staging, and production, keeping your configurations synchronized is critical. One of the best ways to achieve this in Drupal is by leveraging its built-in Configuration Management system. This tool allows you to track and manage site configurations like fields, views, content types, and more.

In this blog post, we will dive into the following key aspects of using Drupal’s Configuration Management effectively:

  1. Configuration Sync: How to use Drupal’s Configuration Management system to manage site configurations across environments.
  2. Store Configuration in Code: Best practices for exporting configurations into code to ensure consistency across environments (local, staging, production).
  3. Managing Configuration Across Teams: How Configuration Management enhances collaboration and reduces errors in multi-developer environments.
  4. Deployment Workflows: Streamlining the deployment process using configuration export/import methods.
  5. Handling Configuration Conflicts: Tips for resolving conflicts that can arise when different environments have diverging configurations.

Let’s explore how you can use Configuration Management to build scalable, maintainable, and consistent Drupal websites.

Introduction to Drupal's Configuration Management System

Drupal’s Configuration Management system, introduced in Drupal 8 and further refined in Drupal 9 and 10, allows you to store the structure and settings of your website as configuration files. This includes:

  • Content types and fields
  • Views
  • Taxonomy vocabularies
  • Block placements
  • Menus and permissions
  • Any other settings related to how the site functions, as opposed to the actual content.

The Configuration Management system provides an efficient way to sync changes made in one environment (such as local development) to other environments (staging, production). This system helps ensure that your environments remain in sync, allowing you to avoid the “works on my machine” problem.

Why Is Configuration Management Important?

Without a solid configuration management process, you may run into serious issues, such as:

  • Inconsistent environments: A common problem is that changes made in a local environment do not get applied to staging or production, leading to errors or mismatches in functionality.
  • Difficult deployments: Moving configurations manually can be error-prone and time-consuming.
  • Untraceable changes: If configurations are changed directly on the production environment, it becomes hard to track what changes were made and why.

Configuration Management solves these issues by making the configuration exportable, trackable, and deployable across multiple environments.

Configuration Sync: Managing Configurations Across Environments

Drupal’s Configuration Management system revolves around the concept of configuration synchronization, often referred to as “config sync.” This system allows you to export your site configurations from one environment (for example, local development) and import them into another environment (for example, production).

Here’s an overview of how it works:

1. Make Changes in One Environment

Typically, you’ll make configuration changes in your local development environment. For example, you might add a new field to a content type, update a view, or modify the permissions of a user role. These changes are automatically tracked by Drupal’s Configuration Management system.

2. Export Configuration

Once your changes are complete, you can export the site configuration to YAML files. This can be done via the admin UI or by using Drush, Drupal’s command-line interface.

  • Admin UI Export:
  • Go to Configuration → Development → Configuration synchronization.
  • Click on Export to download the configuration as a collection of YAML files.
  • Drush Export:
  • Run the following Drush command to export the configuration:
    drush config-export

This exports the configuration into a directory, usually sites/default/files/config_SYNC_HASH, where SYNC_HASH is a unique identifier for your configuration.

3. Version Control

Once exported, the YAML files can be added to version control (such as Git). This allows developers to track configuration changes over time, ensuring that everyone on the team is working with the same configurations. It also provides a clear history of what changes have been made and why.

4. Import Configuration in Another Environment

To apply the configuration changes in another environment, such as staging or production, the exported configuration is imported using the following steps:

  • Admin UI Import:
  • Go to Configuration → Development → Configuration synchronization.
  • Click on Import to upload the configuration YAML files and sync the changes.
  • Drush Import:
  • Run the following Drush command to import the configuration:
    drush config-import

This command reads the YAML files and applies the changes to the site.

Store Configuration in Code: Ensuring Consistency Across Environments

One of the most powerful features of Drupal’s Configuration Management system is the ability to store configuration in code. Storing configuration in code ensures that all environments (local, staging, production) remain consistent.

Benefits of Storing Configuration in Code

  1. Consistency Across Environments: Storing configuration in code ensures that all environments use the same configurations. This prevents bugs caused by configuration mismatches, such as missing fields or views.
  2. Version Control and Audit Trails: By exporting configuration to code, you can version control your site’s configuration files. This means you can track who made changes, when, and why. It also allows you to roll back configurations if something goes wrong.
  3. Collaboration: When working in a team, each developer can export their changes and submit them through Git or another version control system. This makes it easy to review and merge changes, ensuring that the entire team stays in sync.
  4. Easier Deployment: When configuration is stored in code, deploying a new feature or change becomes as simple as running a drush config-import command or importing via the admin interface. This streamlines the process and reduces the risk of manual errors.

Managing Configuration Across Teams

Drupal’s Configuration Management system is especially useful in multi-developer environments. Here’s how you can manage configurations across teams effectively:

1. Use Version Control for Configuration Files

Ensure that all configuration changes are tracked in version control. This allows the team to collaborate without overwriting each other’s changes. When a developer makes a configuration change (such as adding a new view or content type), they can export the configuration to YAML files, commit the changes to Git, and push them for review.

2. Review Configuration Changes Carefully

Because configuration changes are stored as YAML files, they can be reviewed just like code changes. Encourage your team to review configuration changes before merging them into the main branch. This helps catch errors early and ensures that changes are intentional.

3. Sync Configurations Regularly

To avoid conflicts, sync configurations regularly across environments. If multiple developers are working on different features, ensure they import the latest configurations from the main branch before starting their work.

  • Use drush config-import to import the latest configurations.
  • If conflicts arise, resolve them before continuing.

4. Separate Content from Configuration

It’s essential to remember that content and configuration are two different things in Drupal. Configuration refers to how the site is structured and operates, while content is the data within the site (such as blog posts, product descriptions, or user-generated content).

Keeping these two concepts separate is critical, especially when working in teams. Configuration changes should be made in development environments and exported/imported to other environments. Content, on the other hand, typically lives in the production environment and should not be overwritten by configuration imports.

Deployment Workflows with Configuration Management

Deploying configurations across environments (from development to staging to production) is a key part of using Configuration Management in Drupal. A well-structured deployment workflow reduces errors and ensures consistency across all environments.

Example Workflow

  1. Local Development: Developers make configuration changes locally, export the configuration, and commit it to Git.
  2. Testing/Staging Environment: Once configuration changes are committed, they are deployed to a testing or staging environment, where they are imported using drush config-import or the admin UI.
  3. Production Deployment: After testing is complete, the configuration is deployed to the production environment. It’s crucial to run drush config-import again on production to apply the configuration changes.

This workflow ensures that configuration changes are tested before reaching the production site, reducing the risk of introducing bugs.

Handling Configuration Conflicts

One of the challenges in a multi-environment setup is dealing with configuration conflicts. These occur when different environments have diverging configurations, often because changes were made directly on the live site or by multiple developers working in parallel.

Tips for Handling Configuration Conflicts

  1. Avoid Making Configuration Changes on Production: Configuration changes should only be made in development or staging environments and then exported to production. Making changes directly on the production site can cause configuration mismatches, leading to conflicts when importing configurations.
  2. Use a Centralized Development Environment: If possible, use a centralized development or staging environment to test and sync configurations before deploying them to production.
  3. Resolve Conflicts Using Git: When conflicts occur, use Git’s diff tools to compare the conflicting YAML files and resolve them manually. Once resolved, re-export the configuration and import it again.
  4. Communicate with Your Team: In multi-developer environments, regular communication is key to preventing conflicts. Keep your team informed about who is making configuration changes and when, and always sync configurations before starting new work.

Do you agree with the content of this article?

You need to join to the Drupal COE to participate, Log In or Claim your profile now.

Did you find this useful?

Would you suggest another article for the Best Practices category?

You need to join to the Drupal COE to participate, Log In or Claim your profile now.