Backdrop CMS on Pantheon with fast configuration management

Hosting a Backdrop CMS site on Pantheon works great with a couple of minor tweaks. Haven’t heard of Pantheon? They provide high-performance hosting for Drupal and WordPress sites, an impressive suite of dev-ops tools, and a slick environment management dashboard — among plenty of other features. You can try it all for free.

Backdrop CMS on Pantheon works great for simpler sites. For complex builds, there are performance issues. If you’re willing to put up with significant sacrifices in configuration management workflow, Backdrop CMS can run very fast on Pantheon for your complex applications, too.

The configuration below sped up my Backdrop CMS / Pantheon setup by more than 450%. For now, this comes at the cost of downtime for some module, core, and theme updates. See the bottom of the post for those details.

What’s in this post?

In this post I’ll cover getting a vanilla Backdrop CMS site on Pantheon and switching to a read-only configuration management setup aimed at increasing performance. I am assuming you have a local dev environment, and that you use Git. Otherwise it’s pretty straightforward.

The configuration situation: Why is this necessary?

One of the major Backdrop CMS perks as compared to Drupal 7 or even Drupal 8/9 is configuration management. Configuration files are stored in code as JSON files, which means your config is transparent, can be versioned in your repository, and doesn’t imply a few hundred MySQL queries to load up Backdrop CMS and all your modules on every page load.

The problem with this is that reading configuration out of JSON files is actually far slower than MySQL queries on a standard Pantheon setup. To be clear, this is absolutely specific to Pantheon.

How slow? In a production environment on a highly customized Backdrop CMS platform I was seeing an average of 1400ms application response times on Pantheon. Switching to MySQL configuration (not covered in this post) dialed that down to 1000ms. Switching to read-only JSON configuration, covered below, put me under 300ms.

The workaround is easy. On Pantheon hosting the read/write filesystem (the public or private files directories on Drupal and Backdrop CMS installations) is very slow compared to the read only filesystem. That’s because the read/write directories are synchronized networked filesystems, not traditional disk space.

File reads from Pantheon’s read only filesystem are very fast — that’s where your repository goes including the code that runs Backdrop CMS, your modules, your libraries, etc.

So, the basic trick here is to store active configuration files in the read-only filesystem. There are some important details discussed below.

Create a Backdrop CMS site on Pantheon with fast, read-only configuration

Jen Lampton already wrote about moving a Backdrop CMS site to Pantheon. My approach below includes the aforementioned configuration tweaks for a more performant installation.

First you’ll want to create a Pantheon site from the Backdrop CMS custom upstream. Here’s a big button for that:

Create a Backdrop CMS site on Pantheon

Give your site a name and get ready to wait a few minutes. This is the slowest bit.

Once your site is deployed, click the yellow Visit your Pantheon Site Dashboard link.

You should land on the Dev tab of your dashboard. Click the Visit Development Site link and follow onscreen instructions to install your Backdrop CMS site.

Once you land on the homepage of your new site, you’ll want to export configuration by clicking through to the export menu item, or by visiting the /admin/config/development/configuration/full/export path.

Now click the big Export button. We’ll use those files in a minute. Now let’s head back to the Pantheon dashboard, on the Dev tab. Make sure your site is in Git mode, then click Clone with Git.

On your local machine clone the repository and then cd into the project directory. Use the Git clone string provided by Pantheon, and replace backdrop-aten below with your repository name (it will be the name of the directory that gets cloned with Git).

git clone [super_long_repo_string]
cd backdrop-aten

Here we’re going to make a few files and directories.

touch settings.pantheon.php
mkdir config
mkdir config/active
mkdir config/staging

Now let’s edit the contents of our pantheon.yml file and add contents to the settings.pantheon.php file. This is the bulk of the read-only configuration setup.

In your pantheon.yml file:

# IMPORTANT NOTE:
# Do not edit this file unless you are doing so in your custom upstream repository.
# Override the defaults specified here in a site-specific <code>pantheon.yml</code> file.
# For more information see: https://pantheon.io/docs/pantheon-upstream-yml
api_version: 1
php_version: 7.4
protected_web_paths:
 - /files/private
 - /config

In order to keep settings.php as close as possible to its original version, we’ll use our own settings file — settings.pantheon.php — to add our configuration changes. We still need to modify settings.php a little bit to look for our custom settings.

Add this code near the end of the settings.php file, just after the settings.local.php include but before the last bit of code dealing with $_SERVER['PRESSFLOW_SETTINGS'],

/**
 * Include a Pantheon settings file, if available.
 *
 * If possible, modify settings here so that settings.php
 * can stay as close as possible to the backdrop-pantheon
 * upstream.
 */
if (file_exists(__DIR__ . '/settings.pantheon.php')) {
  include __DIR__ . '/settings.pantheon.php';
}

Now we can add our custom configuration setup in the Pantheon specific settings file, which defines new read-only locations for configuration files and lets us override select configuration in non-production environments. Here's what settings.pantheon.php should look like:

<?php
/**
 * Read-only site configuration setup.
 *
 * Point config to web-protected directories that are
 * part of Pantheon's read only file system.
 */
$config_directories['active'] = 'config/active';
$config_directories['staging'] = 'config/staging';
 
/**
 * Configuration overrides for non-production
 *
 * If the site is on Pantheon the 
 * $_ENV['PANTHEON_ENVIRONMENT'] variable will be 
 * either 'dev', 'test', or 'live' - or the name of
 * your multidev environment if you're using that.
 */
if (!isset($_ENV['PANTHEON_ENVIRONMENT']) || (isset($_ENV['PANTHEON_ENVIRONMENT']) && $_ENV['PANTHEON_ENVIRONMENT'] != 'live')) {        
  $config['system.core']['preprocess_css'] = 0;
  $config['system.core']['preprocess_js'] = 0;
}
 

Finally, we need to extract the contents of the configuration archive we downloaded from our site, and paste the contents into the config/active directory we created.

Now we commit our work and push it:

git add .
git commit -m "Read-only configuration changes."
git push origin master

Your Pantheon Dashboard will take a minute to synchronize the environment. When it’s done, refresh your site. Your configuration is now read only which makes for a blazing fast Backdrop CMS / Pantheon site.

How to change configuration

Ok so your site now runs a whole lot faster — but you can’t edit configuration anymore. To test that out navigate over to Configuration > System > Site Information in the admin menu, and try to change any value in that form. Nope.

This means we have two options for configuration management:

1. Use Pantheon’s SFTP mode on the Dev environment (not available on Test or Live) to manage configuration, then commit the results.
2. Manage configuration in a local dev environment and commit the results from there.

To use Pantheon’s SFTP mode to manage configuration, just navigate to the Dev tab on your Pantheon dashboard and click the SFTP mode button. Now back on your site you can change configuration to your heart’s content. Once you’re ready to save the changes, check out your Pantheon dashboard and wait for it to (automatically, hopefully) recognize the changes.

Once you click the Commit button you’re good to go. Now you can deploy the code into your Test and Live environments with your configuration changes all wrapped in.

Managing configuration differences between environments

Finally, you may want to maintain some differences in configuration between various environments. We allowed for this already in the settings.pantheon.php file, in the Configuration overrides for non-production section. One thing to note here is that I have encountered a little difficulty in overriding configuration in very specific circumstances. If you’re having trouble getting an override to take, you might want to look at my Backdrop CMS configuration override issue.

Performing Backdrop CMS core, module, and theme updates

When module, core, or theme updates require configuration changes, the update.php script won't be able to execute successfully on a Pantheon production environment using read-only configuration. This means, in a word, downtime. 

To perform these updates the production site needs to be put into maintenance mode then cloned into the Dev environment where the updates can be performed. After the updates are performed the code changes and database can be pushed into the production environment.

This isn't ideal, and it's something I'm still considering how to best address. Have ideas? Please share below!