MODX CDN integration

Introduction

A MODX CDN integration can deliver CSS, JavaScript, images, and other public files from CDN edge servers closer to visitors. MODX continues to generate pages at the origin while selected static assets are requested through the CDN Service Domain, helping reduce latency and origin traffic.

This guide shows how to configure CDN delivery with a MODX System Setting for theme files and a File System Media Source for managed images. The complete workflow, from configuration through frontend verification, was tested with MODX Revolution 3.2.3-pl.

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 CDN delivery in MODX

  1. Log in to the MODX Manager.
  2. Open Admin → System Settings, click Create, and add a setting with these values:
    • Key: cdn_url
    • Value: https://barsoom-cdn.cdnsun.org
    • Field Type: Textfield
    • Area: Site

    The setting is available in MODX templates as [[++cdn_url]]. Do not add a trailing slash to its value.

    MODX System Settings showing the cdn_url value
  3. Open Media → Media Sources, click Create, and create a File System source named Site Assets. Configure its properties as follows:
    • basePath: assets/uploads/
    • basePathRelative: Yes
    • baseUrl: https://barsoom-cdn.cdnsun.org/assets/uploads/
    • baseUrlRelative: No

    The Base Path must point to the upload directory on the origin. The Base URL must use the matching path on the CDN Service Domain.

    MODX File System Media Source configured with an absolute CDN Base URL
  4. Open Elements → Template Variables and create an Image TV, for example heroImage. Assign the TV to the required template under Template Access. Then open its Media Sources tab and assign Site Assets to the web context.
    MODX Image TV assigned to the Site Assets Media Source
  5. Open Elements → Templates and edit the template used by your resources. Prefix theme file paths with the cdn_url System Setting. Render managed images through the Image TV assigned to the CDN-backed Media Source: 
    <link rel="stylesheet" href="[[++cdn_url]]/assets/css/site.css">
<img src="[[*heroImage]]" alt="">
<script src="[[++cdn_url]]/assets/js/site.js"></script>

    Keep the CSS and JavaScript files at the same paths on the origin. For the Image TV, MODX combines the selected relative file path with the Media Source Base URL.

    MODX template using the cdn_url setting and an Image TV
  6. Open a resource that uses the template, select an image in the Image TV, and click Save. MODX stores the file in the configured Base Path and renders its public URL from the Media Source Base URL.
  7. Open the public site and confirm that the frontend remains styled normally and static assets load from the CDN Service Domain.
    Styled MODX frontend loading CSS JavaScript and an image through CDNsun

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

  ______    ______   __   _   
 /_   _//  /_   _// | || | || 
   | ||     -| ||-  | '--' || 
  _| ||     _| ||_  | .--. || 
 /__//     /_____// |_|| |_|| 
 `--`      `-----`  `-`  `-`