Perch CDN integration

Introduction

Using a CDN with Perch reduces the distance between visitors and uploaded images, documents, stylesheets, and scripts. Static files are delivered from CDN edge servers while Perch and the editable site content continue to run on the origin server.

This guide shows how to integrate Perch 3.2 with CDNsun using the native resource web path and a CDN base URL for assets referenced directly by site templates.

Before you start

  • This tutorial shows how to integrate a CDN service into a website. In this particular demo example we will use:
    • barsoom-cdn.cdnsun.org as the CDN Service Domain, and
    • https://barsoom.cdnsun.org as the website URL (i.e. barsoom.cdnsun.org is the Origin Domain).
  • Please visit the Services/How-To section to obtain your CDN Service Domain.
  • Before you take any steps please back up your files and database.
  • To integrate a CDN service on https:// website the CDN service must have SSL enabled.
  • If your website embeds custom fonts then please first enable CORS for them.
  • Before you take any steps please make sure that your CDN Service Domain is ready-to-use here.

Create CDN Static service

Please refer to Creating a CDN Static service for more details.

Configure Perch resources and site assets

  1. Open perch/config/config.php. Find the default public path for Perch-managed resources:

    define('PERCH_RESPATH', PERCH_LOGINPATH . '/resources');

    Replace it with the complete HTTPS URL that uses your CDN Service Domain:

    define('PERCH_RESPATH', 'https://barsoom-cdn.cdnsun.org' . PERCH_LOGINPATH . '/resources');

    Keep PERCH_RESFILEPATH unchanged. It is the local filesystem path where Perch stores uploaded files, while PERCH_RESPATH controls the public URL written into rendered content.

  2. Configure static files referenced directly by the site's PHP templates. Define one CDN base URL in the template or in a shared site configuration file:

    <?php
$cdnBaseUrl = 'https://barsoom-cdn.cdnsun.org';
?>

    Use that value for the site's stylesheets, JavaScript, and other static template assets:

    <link rel="stylesheet" href="<?= $cdnBaseUrl ?>/assets/site.css">
<script src="<?= $cdnBaseUrl ?>/assets/site.js" defer></script>

    This second setting is necessary because PERCH_RESPATH applies to files managed by Perch, but it does not rewrite static URLs entered directly in site templates.

  3. If the site uses a custom Resource Bucket, set that bucket's web_path to its CDN URL in perch/config/buckets.php. Keep file_path pointed at the corresponding local storage directory:

    <?php
return array(
    'media' => array(
        'type'      => 'file',
        'web_path'  => 'https://barsoom-cdn.cdnsun.org/media',
        'file_path' => '/absolute/path/to/media',
    ),
);

    Apply this only to buckets that the site already uses, and replace the example filesystem path with the bucket's real local path. See the Perch Resource Buckets documentation for the complete bucket configuration format.

  4. Open the public site and confirm that the frontend remains styled normally and static assets load from the CDN Service Domain.

    Styled Perch frontend loading resources and site assets through the CDN Service Domain

Verify & Troubleshoot

  • View HTML source code of your web pages to verify that you are using CDN, you should see source attribute of your images, CSS, JavaScript, etc. beginning with your CDN Service Domain.
    Frontend HTML proof that static assets are loaded from the CDN Service Domain
  • Don't see your CDN Service Domain in the source code of your web pages? If your website is using any cache plug-in/mechanism then you might want to clear/flush its cache.
  • Having trouble with custom fonts? Please refer to Using custom fonts with CDN - setting CORS for more details.
  • Still having trouble? Check your CDN URLs using our content check tool or please refer to Debugging a CDN service for more hints.

Contact Us

            _____     ______  
  ____     |  ___||  /_   _// 
 |    \\   | ||__    `-| |,-  
 | [] ||   | ||__      | ||   
 |  __//   |_____||    |_||   
 |_|`-`    `-----`     `-`'   
 `-`