Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 37 ยท Deployment and Performance

Configuration Management and Deployment

Move Drupal sites between environments: the config system, drush config:export and import, config splits, update hooks, a deployment checklist and a config-diff stand-in.

A Drupal site has two kinds of data. Content (nodes, comments, users, files) lives only in the database of each environment and is created by editors. Configuration (content types, fields, views, blocks, roles, text formats, image styles, module settings) describes how the site is built. Configuration needs to move from your laptop to staging to production without clicking everything again. Drupal's configuration management system exports configuration to YAML files, which you commit to Git, and imports them on the next environment.

Drupal cannot run on this site, so commands are read-only. The TryIt blocks model the import step (finding differences) in JavaScript.

Active configuration and the sync directory

Configuration is stored in the database (the active configuration) and can be exported to a folder (the sync directory) as .yml files. In settings.php:

PHP
$settings['config_sync_directory'] = '../config/sync';

Place the folder outside the web root. A typical workflow:

Terminal
# On your development site, after building a content type or view:
drush config:export --yes        # alias: drush cex
git add config/sync && git commit -m "Add event content type"

# On staging or production, after pulling the code:
composer install --no-dev --optimize-autoloader
drush deploy                     # runs updatedb, config:import, cache:rebuild, deploy hooks

drush deploy is the standard sequence: updatedb, config:import, cache:rebuild and deploy:hook. Before importing, drush config:status and drush config:import --preview=diff show what will change.

The YAML files are readable and diff well:

YAML
uuid: 6f1b2e7c-3a2d-4f0b-b1a6-8f2f1a9c4d11
langcode: en
status: true
dependencies:
  config:
    - field.storage.node.field_date
    - node.type.event
id: node.event.field_date
field_name: field_date
entity_type: node
bundle: event
label: Date
required: true

Two rules matter: the site UUID in system.site.yml must match between environments (clone the database or set it with drush config:set system.site uuid), otherwise import is refused; and configuration is the source of truth, so never change production settings by hand and then forget to export.

Node.js Stand-in: what would config import do?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice the delete: importing removes configuration that is not in the files, which is why a complete, committed export matters.

Environment-specific configuration

Some values must differ per environment: API keys, the site email, a dev-only module. Options:

  • Settings overrides in settings.php or settings.local.php: $config['system.site']['name'] = 'Staging';. Overrides are not part of exported configuration.
  • Config Split (contributed): maintain extra config directories enabled per environment (for example dev turns on Devel and Webprofiler, prod turns on caching modules).
  • Config Ignore (contributed): exclude certain config from import (for example a Webform's live configuration).
  • Secrets never go in YAML: read them from environment variables in settings.php (getenv('MAIL_API_KEY')) or a key module.
PHP
$databases['default']['default'] = [
  'database' => getenv('DB_NAME'),
  'username' => getenv('DB_USER'),
  'password' => getenv('DB_PASS'),
  'host' => getenv('DB_HOST'),
  'driver' => 'mysql',
];
if (file_exists($app_root . '/' . $site_path . '/settings.local.php')) {
  include $app_root . '/' . $site_path . '/settings.local.php';
}

Update hooks and deploy hooks

Configuration alone cannot do everything. If a change must transform existing content or settings, write an update hook in tutorial_notes.install:

PHP
/**
 * Set a default priority on existing notes.
 */
function tutorial_notes_update_10001(&$sandbox) {
  $storage = \Drupal::entityTypeManager()->getStorage('node');
  foreach ($storage->loadByProperties(['type' => 'note']) as $note) {
    if ($note->get('field_priority')->isEmpty()) {
      $note->set('field_priority', 'low')->save();
    }
  }
}

drush updatedb runs each numbered hook once and records it. For batches of work use $sandbox['#finished']. For one-off data changes tied to a release, use a deploy hook (hook_deploy_NAME() in MODULE.deploy.php), run by drush deploy:hook. Always run update hooks before configuration import, because the config may refer to new schema.

Install, uninstall and default configuration

Config in config/install/ of a module is imported when the module is enabled; config/optional/ only if its dependencies exist. Use drush config:export --destination=... or the Devel/drush generate tools to produce the files, then remove the uuid and _core keys.

Deployment checklist

  1. Back up the database (drush sql:dump --gzip --result-file=...) and files.
  2. Put the site in maintenance mode for risky changes (drush state:set system.maintenance_mode 1).
  3. Deploy code (Git pull, or a build artifact), then composer install --no-dev.
  4. drush deploy (database updates, configuration import, cache rebuild).
  5. Check Reports > Status report and a few key pages; turn maintenance mode off.
  6. Keep a rollback plan: previous code release plus database backup.

Use a pipeline (GitHub Actions, GitLab CI) to run composer validate, coding standards, tests and then the deploy, so every release follows the same steps. Hosts such as Pantheon, Acquia, Platform.sh and DDEV-based setups provide the same flow with their own commands.

Node.js Stand-in: update hooks run once, in order

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which of these is configuration, not content?

    Content types, fields, views and roles are configuration and can be exported.
  2. 2. What does drush deploy do?

    It is the standard release command that bundles these steps in order.
  3. 3. Where should secrets such as API keys be stored?

    Config files are committed to Git; secrets must stay out of them.
  4. 4. Why can config import fail between two unrelated sites?

    Drupal refuses to import configuration from a different site.

Summary

  • Configuration (structure) is exported as YAML and deployed with Git; content stays in each database.
  • drush cex exports; drush deploy runs updates, imports configuration and rebuilds caches.
  • Use settings overrides, Config Split and environment variables for per-environment values.
  • Update hooks transform existing data and run once, in order.
  • Back up, deploy, verify, and keep a rollback plan.

Next: Caching and Cache Tags