Skip to main content
Last Reviewed: December 13, 2022

Environment-Specific Configurations for Drupal

Manage verbose debugging options and system performance settings per environment on Pantheon using our service configuration files and Drupal's configuration override system.

This section provides information on how to manage verbose debugging options and system performance settings for individual environments.

The following instructions enable Twig debugging and set development-friendly performance options across Pantheon's pre-production environments (Dev & Multidevs). This approach prevents debugging output and potentially harmful performance settings from being deployed to staging and production environments (Test and Live).

Enable Twig Debugging on Dev & Multidevs

Pantheon handles the inclusion of service configuration files. The default file provided has everything you need, so enabling Twig debugging is simple:

  1. Clone the site's codebase using the Git command string provided on the Site Dashboard or via Terminus if you haven't done so already.

    terminus connection:info <site>.dev --fields='Git Command' --format=string
  2. Navigate to the site's docroot and rename the existing default service file for pre-production environments:

    mv sites/default/ sites/default/services.pantheon.preproduction.yml
  3. Stage, commit, and push your changes to Pantheon:

    git commit -am "Create pre-production service config file and enable Twig debug"
    git push -u origin master
  4. Clear caches on Dev within the Site Dashboard or via Terminus:

    terminus env:clear-cache <site>.<env>
  5. Verify configuration by inspecting the page source on the Dev environment's URL. You should see markup similar to the following:

    <!-- THEME DEBUG -->
    <!-- THEME HOOK: 'page' -->
      * page--front.html.twig
      * page--.html.twig
      x page.html.twig
    <!-- BEGIN OUTPUT from 'core/themes/bartik/templates/page.html.twig' -->
     <div id="page-wrapper">
       <div id="page">
         <header id="header" class="header" role="banner" aria-label="Site header">
           <div class="section layout-container clearfix">

Refer to Creating a services.yml File for Drupal for more information on Pantheon's service configuration files for Drupal.

Enable Cacheability Debugging on Dev and Multidevs

  1. Add the sites/default/services.pantheon.preproduction.yml file to your project if you have not done so already.

    • This service file is used to manage settings across Pantheon's development (Dev and Multidev) environments. Settings in this file are not applied to production (Test and Live) environments.
  2. Enable Drupal's CacheableResponseInterface to help debug your cache by setting the http.response.debug_cacheability_headers parameter to true:

     http.response.debug_cacheability_headers: true
  3. Stage, commit, and push your changes to Pantheon:

    git commit -am "Pre-production enable cacheability debug service"
    git push
  4. Verify service setting and debug cache behavior by inspecting response headers on a development environment URL. If enabled, cacheable responses will return X-Drupal-Cache-Tags and X-Drupal-Cache-Contexts headers such as:

    $ curl -I | grep -E 'X-Drupal-Cache-Context|X-Drupal-Cache-Tags'
    X-Drupal-Cache-Contexts: languages:language_interface route theme url.path.parent url.query_args user.node_grants:view user.permissions user.roles:authenticated
    X-Drupal-Cache-Tags: block_view config:block.block.bartik_account_menu config:block.block.bartik_branding config:block.block.bartik_breadcrumbs config:block.block.bartik_content config:block.block.bartik_footer config:block.block.bartik_help config:block.block.bartik_local_actions config:block.block.bartik_local_tasks config:block.block.bartik_main_menu config:block.block.bartik_messages config:block.block.bartik_page_title config:block.block.bartik_powered config:block.block.bartik_search config:block.block.bartik_tools config:block_list config:color.theme.bartik config:search.settings config:user.role.anonymous config:views.view.frontpage http_response node_list rendered

Refer to Creating a services.yml File for Drupal for more information on Pantheon's service configuration files for Drupal.

Troubleshoot 503 Response: Header Overflow

Responses with HTTP headers that exceed 10k return 503 Header Overflow errors. If you get this error after enabling cacheability debugging, disable it in the appropriate service file.

  http.response.debug_cacheability_headers: false

This issue can be caused by a number of scenarios related to cache tags, such as many fields on a content type causing Drupal to generate really long HTTP headers. For more information on cache tags, see Cache tags.

Override System Performance Settings Per Environment

  1. Use the PANTHEON_ENVIRONMENT constant and Drupal's override system within settings.php to enforce performance configurations based on the current Pantheon server environment:

    if (isset($_ENV['PANTHEON_ENVIRONMENT'])) {
    	 switch($_ENV['PANTHEON_ENVIRONMENT']) {
    		case 'live':
    		case 'test':
            $config['system.performance']['cache']['page']['use_internal'] = TRUE;
            $config['system.performance']['css']['preprocess'] = TRUE;
            $config['system.performance']['css']['gzip'] = TRUE;
            $config['system.performance']['js']['preprocess'] = TRUE;
            $config['system.performance']['js']['gzip'] = TRUE;
            $config['system.performance']['response']['gzip'] = TRUE;
            $config['views.settings']['ui']['show']['sql_query']['enabled'] = FALSE;
            $config['views.settings']['ui']['show']['performance_statistics'] = FALSE;
            $config['system.logging']['error_level'] = 'none';
    		case 'dev':
          default :
            $config['system.performance']['cache']['page']['use_internal'] = FALSE;
            $config['system.performance']['css']['preprocess'] = FALSE;
            $config['system.performance']['css']['gzip'] = FALSE;
            $config['system.performance']['js']['preprocess'] = FALSE;
            $config['system.performance']['js']['gzip'] = FALSE;
            $config['system.performance']['response']['gzip'] = FALSE;
            $config['views.settings']['ui']['show']['sql_query']['enabled'] = TRUE;
            $config['views.settings']['ui']['show']['performance_statistics'] = TRUE;
            $config['system.logging']['error_level'] = 'all';
            # $settings['cache']['bins']['render'] = 'cache.backend.null';
            # $settings['cache']['bins']['dynamic_page_cache'] = 'cache.backend.null';
  2. Stage, commit, and push your changes to Pantheon:

    git commit -am "Override system performance configurations per env"
    git push
  3. Verify overridden configurations for each on the Dev environment within the Drupal UI using the Configuration Manager core module (/admin/config/development/configuration/single/export) or via Terminus:

    terminus drush <site>.<env> -- config-get system.performance --include-overridden
    terminus drush <site>.<env> -- config-get system.logging --include-overridden
    terminus drush <site>.<env> -- config-get views.settings --include-overridden

    Overridden configurations are not shown within Drupal's admin interface; this behavior is intentional.

  4. Deploy to Test and verify desired configurations are present. If everything looks good, deploy to Live.

Rotate hash_salt setting

You can use the Terminus env:rotate-random-seed command if you need to change the value for the keys and salts. This command invalidates all one-time login links and forces all users to login again.

Inclusions and Loading Order of Settings and Services Files

Settings FileInclusions




More Resources