3SD staff handbook

Appearance

WP Super Cache ​

Documentation: Initial WP Super Cache Setup and Configuration

Wiki: WP Super Cache

Preparation ​

Before configuring this plugin you should create a list of all pages that shouldn't be cached. This includes any pages that have CiviCRM content:

  • the CiviCRM base page
  • event pages
  • contribution pages
  • public CiviCRM forms - profiles or FormBuilder

We should add these pages to the list of 'Rejected URL Stings' in the advanced settings (see below). A simple way to do this is to ignore any URLs that contain the string 'civi'.

Installation and configuration ​

Perform the following steps in the dev environment:

  • Download the WP Super Cache plugin code (but don't activate the plugin yet)

  • Commit the plugin files to version control

  • Edit all three docker-compose.*.yml files to add the environment variables

    yml
    services:
  app:
    ...
    environment:
      ...
      - WP_CACHE=TRUE
      - WP_CACHE_SECRET
      - WP_CACHE_DEBUG_USERNAME
      - WP_CACHE_DEBUG_LOGFILE

  • Edit docker-compose.prod.yml and docker-compose.test.yml to add a cache volume

    yml
    services:
  app:
    ...
    volumes:
      ...
      - cache:/var/www/html/wp-content/cache
      ...
volumes:
  ...
  cache:
  ...

  • Restart the docker container with docker compose up -d

  • Add a line to .gitignore to ignore cache files

    /src/wordpress/wp-content/cache

  • Ensure the wp-config.php file is writable (this is needed to activate the plugin but any changes made by the plugin should be reverted)

    sh
    docker compose exec -u civicrm app chmod +w wp-config.php

  • Create a wp-config-extra.php file with the following lines (or add to the existing file):

    php
    <?php
/**
* Additional site specific WordPress config
*/

/**
* WP Super Cache settings
*/
if ( getenv( 'WP_CACHE' ) === 'TRUE' ) {
  define( 'WP_CACHE', true );
  define( 'WPCACHEHOME', '/var/www/html/wp-content/plugins/wp-super-cache/' );
}

  • Activate the plugin

  • Configure the advanced settings

    • Enable caching
    • Cache delivery method = Expert
    • Disable caching for logged in visitors = Yes
    • Compress pages so they’re served more quickly to visitors = Yes
    • Cache rebuild = Yes
    • Extra homepage checks = Yes

  • Rejected URL Strings - don't cache any forms - see above

    wp-.*\.php
index\.php
civi

  • Visit the debug settings page - this generates the debug log filename and username

  • The configuration settings are saved to wp-content/wp-cache-config.php

  • Copy secrets from wp-cache-config.php to .env

    ini
    WP_CACHE_SECRET=
WP_CACHE_DEBUG_LOGFILE=
WP_CACHE_DEBUG_USERNAME=

  • Edit the wp-cache-config.php file to use environment variables by replacing the secrets with the following lines - make sure you delete the existing variable definition so that these aren't overwritten

    php
    $cache_page_secret       = getenv( 'WP_CACHE_SECRET' );
$wp_cache_debug_log      = getenv( 'WP_CACHE_DEBUG_LOGFILE' );
$wp_cache_debug_username = getenv( 'WP_CACHE_DEBUG_USERNAME' );

  • Restart the docker container with docker compose up -d

  • Commit the changed files to version control - this should include

    src/wordpress/wp-content/advanced-cache.php
src/wordpress/wp-content/wp-cache-config.php
src/wordpress/.htaccess
src/wordpress/wp-config-extra.php
.gitignore
docker-compose.dev.yml
docker-compose.prod.yml
docker-compose.test.yml

  • Don't commit any changes to src/wordpress/wp-config.php. Any changes made to this file by activating the plugin should be reverted.

Testing ​

To check that caching is working visit the site in an incognito window (caching is disabled for logged in users). Check the bottom of the HTML for a comment like this:

html
<!-- Dynamic page generated in 0.112 seconds. -->
<!-- Cached page generated by WP-Super-Cache on 2024-12-04 09:32:40 -->
<!-- Compression = gzip -->

The time shouldn't change when you reload the page.

Pages that have been excluded from caching shouldn't have this comment at the bottom.

Check that public forms are working correctly (caching can break CSRF tokens). To test this fully, you need to test the page twice with a break of at least five minutes - the first time you submit the form it may work as it has been freshly created, the second time might not work as it is using an old cached token.

Deployment ​

To deploy to test or prod follow the steps below - these can be copied and pasted into an issue.

md
- [ ] Add secrets to `.env` - copy from dev
  ```bash
  WP_CACHE_SECRET=
  WP_CACHE_DEBUG_USERNAME=
  WP_CACHE_DEBUG_LOGFILE=

  • [ ] Merge and pull MR

  • [ ] Run the following commands

    bash
    # Create cache folder (if required)
ls -al src/wordpress/wp-content
mkdir src/wordpress/wp-content/cache

# Restart container
docker compose up -d

# Set folder ownership
docker compose exec app ls -al wp-content
docker compose exec app chown civicrm:civicrm wp-content/cache

# Activate plugin
docker compose exec -u civicrm app wp plugin activate wp-super-cache

Note: the configuration is committed to version control and will be read only on test and production. This means that it isn't possible to alter the settings via the UI.