Discourse CDN integration

Introduction

A Discourse CDN integration can serve stylesheets, JavaScript, theme files, avatars, and other static assets from edge servers closer to forum visitors. Dynamic forum pages and MessageBus requests continue to use the Discourse origin while the CDN reduces static-file traffic to it.

This guide shows how to configure Discourse's native Pull CDN setting in the official Docker installation. The procedure was tested with Discourse 2026.8.0-latest.1.

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.

How to enable CDN in Discourse

  1. Connect to the Discourse server, change to the installation directory, and open containers/app.yml: 
    cd /var/discourse
nano containers/app.yml

    In the existing env: section, add DISCOURSE_CDN_URL with the complete HTTPS URL of your CDN Service Domain: 

    env:
  DISCOURSE_CDN_URL: "https://barsoom-cdn.cdnsun.org"

    Keep the existing entries in the env: section and use the same YAML indentation as the other DISCOURSE_ variables. The URL must include https://; protocol-relative URLs beginning with two slashes are not supported.

  2. Save app.yml, return to /var/discourse, and rebuild the application container so Discourse compiles and publishes asset URLs with the new CDN setting: 
    ./launcher rebuild app

    Wait until the rebuild completes and the application container is running again before opening the forum.

  3. Open the public site and confirm that the frontend remains styled normally and static assets load from the CDN Service Domain.
    Styled Discourse forum loading static 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

  _  __    _____     ______  
 | |/ //  |  ___||  /_____// 
 | ' //   | ||__    `____ `  
 | . \\   | ||__    /___//   
 |_|\_\\  |_____||  `__ `    
 `-` --`  `-----`   /_//     
                    `-`