Ruby on Rails CDN integration

Introduction

A Ruby on Rails CDN integration can deliver digest-stamped CSS, JavaScript, images, and other static files from edge servers closer to application visitors. Dynamic application routes remain on the Rails origin while the CDN handles repeat requests for public assets.

This guide shows how to configure the native Rails asset host for a production application. The procedure was tested with Ruby on Rails 8.1.3.1 and Propshaft 1.3.2.

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 Ruby on Rails

  1. Add the complete HTTPS URL of the CDN Service Domain to the production environment. For example, set: 
    CDN_HOST=https://barsoom-cdn.cdnsun.org

    Keep this value in the deployment environment instead of hard-coding it in application templates. The same configuration can then use a different CDN Service Domain in staging.

  2. Open config/environments/production.rb and set the Rails asset host from that environment variable: 
    config.asset_host = ENV["CDN_HOST"]

    Rails applies this host to URLs generated by its asset helpers. Application routes and dynamic controller responses continue to use the origin domain.

  3. Reference stylesheets, JavaScript entrypoints, and images through Rails helpers instead of writing static paths manually. A standard application layout can contain: 
    <%= stylesheet_link_tag :app, "data-turbo-track": "reload" %>
<%= javascript_importmap_tags %>
<%= image_tag "logo.svg", alt: "Company logo" %>

    In production, these helpers add the CDN Service Domain and the digest-stamped asset filename. Files written as literal paths such as /images/logo.svg do not use the configured asset host.

  4. Keep cache headers enabled for fingerprinted production assets. Rails 8 applications include this setting in config/environments/production.rb by default: 
    config.public_file_server.headers = {
  "cache-control" => "public, max-age=#{1.year.to_i}"
}

    The content digest changes when an asset changes, so the generated filename can be cached for a long period without serving an older revision under the same URL.

  5. Precompile the asset pipeline as part of the production deployment: 
    RAILS_ENV=production bin/rails assets:precompile

    With Propshaft, the command writes digest-stamped files and the asset manifest to public/assets/. Deploy that directory with the Rails application so the same paths are available when the CDN requests them from the origin.

  6. Complete the cross-origin asset setup described in the CDNsun CORS configuration guide. This is required when JavaScript modules generated by Importmap load from a different domain.

  7. Active Storage note: The asset host setting applies to asset-pipeline files, not uploaded attachments. To cache Active Storage blobs and image variants through a CDN, use proxy mode and generate attachment URLs with the CDN host as described in the official Rails Active Storage CDN guide.

  8. Open the public site and confirm that the frontend remains styled normally and static assets load from the CDN Service Domain.
    Styled Ruby on Rails application loading Propshaft 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

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