Setting up a Brand new Backdrop site on Pantheon

Building a Backdrop site on pantheon can be done many ways. Below is my preferred method. It includes the following Pantheon options:

• Web Docroot
• Protected Web Paths
• Versioned configuration (staging directory only)
• Unique active configuration per enviornment
• Support for local development using ddev

Step 1) Arrange files on disk how you'd like to have them

Backdrop code

• Create a new directory named web.
• Move the entirety of the Backdrop CMS codebase into the new webdirectory.
• The only files that remain outside the web directory are: `pantheon.yml` and `pantheon.upstream.yml`.

Add new private directories and files

• Add a PATCHES.md file here.
• Add a directory named config
• Inside the config directory add two additional directories, staging and local-config.

Step ) Update your Pantheon.yml file

Here we need to tell Pantheon how to interact with our changed files on disk. Add the following:

# Nested Docroot
# https://pantheon.io/docs/pantheon-yml#nested-docroot
web_docroot: true

# Protected Web Paths
# https://pantheon.io/docs/pantheon-yml#protected-web-paths
protected_web_paths:
  - /config
  - /PATCHES.md
  - /web/files/private
  - /web/files/config

# (OPTIONAL) PHP Version:
# https://pantheon.io/docs/pantheon-yml#php-version
# Set site's PHP version to 8.3
php_version: 8.3

Step ) Update your settings.php file

Here we make changes to the default Backdrop settings that are preferable on Pantheon. Change the following:

Change the default values for Site configuration files location

Setting the default values to locations for local development prevents accidental overwriting in high-risk locations.

$config_directories['staging'] = '../config/staging';     /* versioned */
$config_directories['active'] = '../config/local-active'; /* not versioned */
/* Active values are overridden settings.pantheon.php */

Skip the configuration staging directory cleanup

Changing this value prevents the config files from being deleted from the staging directory after import.

$config['system.core']['config_sync_clear_staging'] = 1;

Disable backups during the update.php process

Because Pantheon has its own backup process, we can disable Backdrop's built-in backups.

$settings['backup_directory'] = 'FALSE';

Confirm other settings files have been loaded

Check at the bottom of this file that both the settings.pantheon.php file, and the settings.local.php are being loaded, and in that order.

Step ) OPTIONAL: Update your settings.pantheon.php file

Pantheon's provided settings file should be sufficient for many set-ups, but I want three different active config directories (one for dev, test, and live).

Set the location for ACTIVE configuration files, specific to each enviornment

/**
 * Site configuration files location.
 * - All sites use the same staging directory, but unique active directories.
 * - Staging lives outside the web root. Not web-writable, managed by Git.
 * - Active lives inside the files directory. Web-writable. Not managed by Git.
 */
if (defined('PANTHEON_ENVIRONMENT')) {
  if (PANTHEON_ENVIRONMENT == 'dev') {
    $config_directories['active'] = 'files/config/dev-active';
  }
  else if (PANTHEON_ENVIRONMENT == 'test') {
    $config_directories['active'] = 'files/config/test-active';
  }
  else if (PANTHEON_ENVIRONMENT == 'live') {
    $config_directories['active'] = 'files/config/live-active';
  }
}

OPTIONAL Update the Trusted host settings

This ensures only pantheonsite.io</code< domains will reach the <code>dev and

test</code< sites. (Do not change this if you are planning on adding custom domains to either of these environments.)

<code>
/**
 * Trusted host settings
 */
if (isset($_ENV['PANTHEON_ENVIRONMENT'])) {
  if (in_array($_ENV['PANTHEON_ENVIRONMENT'], array('dev', 'test'))) {
    $settings['trusted_host_patterns'][] = "{$_ENV['PANTHEON_ENVIRONMENT']}-{$_ENV['PANTHEON_SITE_NAME']}.pantheonsite.io";
  }
  else {
    $settings['trusted_host_patterns'][] = '.*';
  }
}

Step ) Create a new settings.local.php file

This file contains overrides that are specific only to the individual enviornment where the code is actively running. This file is not usually in version control, and secrets and sensitive information can be placed into this file.

Because I am currently setting up my local development enviornment, I am going to add the following items to make local development easier for me:

Site configuration files location

Note that we do not need a section for Site configuration files, because the default configuration in settings.php is the configuration we need for local development.

Debugging and cache control settings

  // Disable page cache.
  $config['system.core']['cache'] = FALSE;
  // Disable CSS aggregation.
  $config['system.core']['preprocess_css'] = FALSE;
  // Disable JS aggregation.
  $config['system.core']['preprocess_js'] = FALSE;

  // Show all errors for debugging.
  $config['system.core']['error_level'] = 'all';

  // Show HTML comments for theme development.
  $config['system.core']['theme_debug'] = TRUE;

Step ) Run the Backdrop CMS installer

Run the standard Backdrop CMS install process on the Pantheon -dev instance, and confirm the site functions as expected.
Check the status report to confirm:

• The configuration directories are where you specified.
• The files directory is writable.
• Check the PHP version