Documentation Level: 
Intermediate
Documentation Status: 
No known problems

This is an idea from @populist and @davidstrauss based on how the config directory is being managed for on the Pantheon platform.

  • Drush works nicely with this approach. Read more about how if you use Drush.
  • Bee also works nicely with this approach. There are Bee versions of the Drush commands used with this approach.

Configuration directory set-up

config/
  config/active
  config/staging <-- track via Git
  1. Move config outside of files (and preferably outside the docroot)
  2. Update settings.php to point at the new locations of active & staging

A good arrangement for your repositories (both local and production) is

repo <-- track via Git
config/
  config/active <-- untracked, e.g., Git ignore
  config/staging
webroot <-- Backdrop distribution files (except config) go in here
  core
  ...
  files <-- Untracked directory or symlink to directory outside of docroot
  settings.php
  settings.local.php  <-- Untracked, e.g., Git ignore

Additional set up

  1. In settings.php, uncomment the line
$config['system.core']['config_sync_clear_staging'] = 0;

This will ensure that staging is not cleared after a configuration sync.

Local site settings.php example:

/**
 * Site configuration files location.
 */
$config_directories['active'] = '../config/active';
$config_directories['staging'] = '../config/staging';

Production site settings.php example:

/**
 * Site configuration files location.
 */
$config_directories['active'] = '../config/active';
$config_directories['staging'] = '../config/staging';

Deploying to prod - moving upstream

  1. local: Replace the contents of the staging directory with the contents of the active directory, by one of:

    1. Manually delete all files in the staging directory.
    2. Manually copy the all the files from the active directory into the staging directory.

    OR

    Run drush bcex on the local system.

    OR

    Run bee bcex on the local system.

  2. local: git add & git commit all files in staging.

  3. local: git push to get all files into the Git repository.
  4. production: git pull to pull all config changes into staging on the production server.

  5. production: Import from staging, via one of:

    Run the config importer (via Backdrop UI at admin/config/development/configuration/sync).

    OR

    Run drush bcim on the production system.

    OR

    Run bee bcim on the production system.

Syncing local to prod - moving downstream

  1. production: Replace the contents of the staging directory with the contents of the active directory, by either:

    1. Manually delete all files in the staging directory.
    2. Manually copy the all the files from the active directory into the staging directory.

    OR

    Run drush bcex on the production system.

    OR

    Run bee bcex on the production system.

  2. production: git add & git commit all files in staging.

  3. production: git push to get all files into the Git repository.
  4. local: git pull to pull all config changes into staging on the local system.

  5. local: Import from staging, via one of:

    Run the config importer (via Backdrop UI at admin/config/development/configuration/sync).

    OR

    Run drush bcim on the local system.

    OR

    Run bee bcim on the local system.

Upsides:

  • No extra directories needed.
  • No renaming of directories required.
  • active and staging directories behave the same for both local and production.

Downsides:

  • Manual copying of directories required for every config deployment (although drush bcex simplifies this process).
  • Accidental reverts are possible: If there was ever a config change made to any site that was not copied out of the active directory and committed in the staging directory, the next time the config importer is run (via Backdrop UI) that change will be lost.

Before starting the process of deployment to production from the local machine, since you will be replacing the contents of the current staging directory on your local machine, it is a good idea to check two things on the local machine:

  • Check the config importer at /admin/config/development/configuration/sync to see current differences between staging and active;
  • Run git status to see any currently uncommitted changes to staging.

Any differences you see in either place should be due to the config changes you intend to deploy; if you see any difference that you don't recognize, then it's worth looking into further before proceeding.