Using Drupal Configuration Management to Version Control Site Settings

Set up Drupal Configuration Management (CMI)

Drupal’s Configuration Management system stores site configuration – such as views, content types, fields and block layouts – as YAML files outside the database. By committing those files to Git you can track changes, replicate settings across environments and deploy configuration with a single command.

1. Choose a location for the sync directory

The directory must be outside the document root so that the YAML files cannot be fetched via a web request. A common pattern is to create a ../config/sync folder relative to the site’s web/ or public_html/ directory.

# Example: from the site root
mkdir -p ../config/sync
chmod 750 ../config/sync
chown -R www-data:www-data ../config/sync   # adjust to your web‑server user

2. Tell Drupal where to look

Add the following line to settings.php (or settings.local.php for environment‑specific overrides). The path must be an absolute filesystem path.

$settings['config_sync_directory'] = '/var/www/example.com/../config/sync';

3. Export the current configuration

Run Drush from the site root. The command reads the active configuration and writes YAML files to the sync directory.

drush cex

After the command finishes, inspect the directory: you should see files like core.entity_form_display.node.article.default.yml and views.view.frontpage.yml.

4. Import configuration into another environment

Copy the entire sync directory (or push it via Git) to the target server, ensure the same $settings['config_sync_directory'] points to it, then run:

drush cim

Drush will compare the YAML with the active configuration and apply any differences. When the import completes, clear caches:

drush cr

Limits and considerations

• Configuration only: CMI does not version content (nodes, users, comments). Those remain in the database and require separate strategies such as the Migrate module or database dump.
• UUID dependence: Exported configuration contains universally unique identifiers (UUIDs). Importing will fail if the target site already has configuration with conflicting UUIDs or if a referenced module provides different UUIDs.
• Size and memory: Very large configuration sets (hundreds of views, many custom fields) can increase import time and peak memory usage. Monitor drush cim output for PHP memory warnings and consider splitting configuration into feature modules if needed.

Common mistakes and how to avoid them

1. Placing the sync directory inside the web root: This makes YAML files downloadable. Verify that http://your‑site.com/config/sync/ returns a 403 or 404, not a file listing.
2. Incorrect file‑system permissions: The web‑server user must be able to read and write the directory. Too permissive (777) exposes the files; too restrictive (700) prevents Drush from updating them.
3. Forgetting to clear caches after import: Until the cache is rebuilt, the UI may show stale settings. Always run drush cr (or drush cache-rebuild) after cim.
4. Importing configuration that depends on missing modules: If a YAML file references a block provided by a module that is not enabled, Drush will abort. Enable all required modules before running cim.
5. UUID mismatch between source and target: When cloning a database, ensure the configuration UUIDs are in sync, or use drush cim --partial to import only the configuration that can be safely applied.

Verification checklist

• Confirm that the directory defined in $settings['config_sync_directory'] exists, is writable by the web‑server user, and is not accessible via HTTP.
• Run drush status and look for the line “Config sync directory” to verify the path Drupal is using.
• After drush cim, clear caches (drush cr) and check the UI (e.g., Structure → Content types or Views) to see that the imported configuration is active.