Skip to main content

Integrate a CDN resource with Drupal

The Drupal CDN module rewrites public file URLs so CSS, JavaScript, images, fonts, and videos load through a Orange's CDN domain, while HTML pages, REST responses, and private files continue from Drupal.

Administrator access to Drupal, Composer, an active CDN resource, and an HTTPS-enabled custom domain are required. The CDN resource must use the Drupal site as its origin. Back up the Drupal files and database before installing the module.

  1. 1

    Configure query string caching

    Drupal image styles append an itok query parameter. The Ignore query string option controls whether query parameters are included in the CDN cache key.

    In the CDB Technical Web Portal, open the CDN resource. Under Cache, open Query string.

    Leave Ignore query string disabled so each itok value stays in the cache key.

    On a cache miss, the CDN forwards the original query string to the origin, including itok.

  2. 2

    Install the CDN module

    From the Drupal project root, run the command for the installed Drupal version.

    For Drupal 9.4 through Drupal 10, including 10.3, install CDN 4.1.0:

    composer require 'drupal/cdn:^4.1'

    For Drupal 11, PHP 8.3 is required for CDN 5.0.0-alpha1, because Composer rejects the package on an older PHP version:

    composer require 'drupal/cdn:^5.0@alpha'

    drupal/cdn:^5.0@alpha is a prerelease.

  3. 3

    Enable the configuration modules

    In the Drupal administration panel, navigate to Manage > Extend. Select CDN and CDN UI, then click Install.

    CDN UI provides the browser-based settings and can be uninstalled after the CDN configuration is complete.

  4. 4

    Open the CDN settings

    Navigate to Configuration > Development > CDN, or open /admin/config/development/cdn.

  5. 5

    Configure the CDN mapping

    Enable the CDN module and configure a simple Origin Pull mapping. In the CDN mapping field, enter the full HTTPS custom-domain URL — https://cdn.example.com.

    Use the same custom domain configured for the Orange's CDN resource. The HTTPS scheme prevents mixed-content errors when Drupal pages load over HTTPS.

  6. 6

    (Optional) Set file caching

    On the CDN settings page, enable Forever cacheable files to generate long-lived, immutable asset URLs.

    For sites with many files, this option can increase origin load because Drupal may serve cache misses through PHP. Leave it disabled unless the origin can handle that behavior or the web server is configured to serve the generated paths directly.

  7. 7

    Review and save the settings

    Confirm that the module status is enabled and the mapping uses the HTTPS CDN domain, then click Save configuration.

  8. 8

    Verify CDN delivery

    Open a public Drupal page and use the browser developer tools:

    1. Open the Network panel.
    2. Reload the page.
    3. Filter requests for CSS, JavaScript, images, fonts, or videos.
    4. Confirm that public file URLs use cdn.example.com and return successful responses.
    5. Request an image-style URL that contains ?itok= through the CDN domain and confirm that the derivative is returned.

    If assets still use the Drupal origin, clear the Drupal cache and verify that the CDN module is enabled and the mapping URL is saved.