Ghost CDN Integration

Introduction

A Ghost CDN integration can improve delivery of stylesheets, JavaScript, images, and other static files by serving them from your CDN Service Domain instead of directly from the origin server. This can reduce latency for visitors and offload static traffic from the origin.

This guide shows how to configure Ghost's native asset, image, media, and file URLs with its built-in local storage. The procedure was tested on Ghost 6.64.0 and does not require a storage adapter or CDN plugin.

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 Ghost

  1. Connect to the server hosting Ghost and open its active config.production.json file. With a Ghost-CLI installation, this file is in the Ghost installation directory. With Docker, edit the host file mounted at /var/lib/ghost/config.production.json inside the container. These settings are server configuration options, not fields in Ghost Admin.

    Keep the existing database, mail, server, and storage settings. Leave the main url pointing to your website, not to the CDN Service Domain: 

    "url": "https://barsoom.cdnsun.org"
  2. Add the following urls object at the top level of the configuration file. If it already exists, update its entries instead of adding a duplicate object. Replace the example domain with your CDN Service Domain and keep the file valid JSON, including commas between properties. 
    "urls": {
    "assets": "https://barsoom-cdn.cdnsun.org",
    "image": "https://barsoom-cdn.cdnsun.org",
    "media": "https://barsoom-cdn.cdnsun.org",
    "files": "https://barsoom-cdn.cdnsun.org"
}

    With local storage, use the same HTTPS base URL for all four values, without a trailing slash. Do not append paths such as /assets or /content/images. Ghost adds the file path itself, so including it here can produce broken URLs.

    • assets sets the base URL for theme resources generated with Ghost's asset helper, such as CSS and JavaScript.
    • image sets the base URL for Ghost-managed images, including feature images, article images, galleries, and responsive sizes.
    • media sets the base URL for uploaded audio and video referenced in content.
    • files sets the base URL for uploaded files referenced in content, such as PDF downloads.

    Files remain in local storage, and Ghost continues to generate image sizes. The CDN retrieves files from the origin as needed. Theme resources must use Ghost's asset helper to follow the asset setting; hard-coded URLs are not automatically rewritten.

  3. If your deployment uses environment variables for these settings, update them instead of the JSON file. Environment variables take precedence over file values. Their equivalent names and values are: 
    urls__assets=https://barsoom-cdn.cdnsun.org
urls__image=https://barsoom-cdn.cdnsun.org
urls__media=https://barsoom-cdn.cdnsun.org
urls__files=https://barsoom-cdn.cdnsun.org
  4. Save the configuration and restart Ghost. For a Ghost-CLI installation, run the following command from the Ghost installation directory as the installation user: 
    ghost restart

    For Docker with a mounted configuration file, restart the Ghost container. The container in this example is named barsoom-ghost; substitute your own container name: 

    docker restart barsoom-ghost

    If you changed environment variables in Docker Compose, apply the updated service definition from its project directory instead. Restarting the existing container alone does not update its environment: 

    docker compose up -d

    Wait for Ghost to finish starting. See the Ghost configuration documentation for details about configuration files and environment variables.

  5. Sign in to Ghost Admin on your website domain and open a post under Posts. Existing Ghost-managed images do not need to be moved or uploaded again. You can continue adding images through the editor as usual. If you change a published post, click Update to save it.

    Images may still use the origin URL inside the editor. Ghost generates their CDN URLs when rendering the public site.

    Ghost editor showing the Barsoom publishing article and its uploaded feature image
  6. Open the public site and confirm that the frontend remains styled normally and static assets load from the CDN Service Domain.
    Styled Barsoom Ghost frontend with theme assets and uploaded images delivered 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

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