> ## Documentation Index
> Fetch the complete documentation index at: https://gcore-doc-1894.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate a CDN resource with Craft CMS

Craft CMS 5 generates public asset URLs from the filesystem assigned to each asset volume. Configure the filesystem Base URL with a Gcore CDN domain so Craft templates return CDN URLs for those assets.

Administrator access to Craft CMS, an existing CDN resource, and an HTTPS-enabled [custom domain](/cdn/cdn-resource-options/general/create-and-set-a-custom-domain-for-the-content-delivery-via-cdn) are required. Back up the Craft files and database before changing storage settings.

<Steps>
  <Step title="Map the CDN resource to the asset location">
    Identify the public path where Craft stores the assets — `/uploads/` in a typical local setup. In the [Gcore Customer Portal](https://portal.gcore.com/cdn/resources/list), configure the CDN origin so the same path resolves to that asset directory.

    The CDN domain and the Craft filesystem must use matching paths. If the CDN domain is `cdn.example.com` and the asset path is `/uploads/`, an origin request for `/uploads/image.jpg` must return the corresponding file.
  </Step>

  <Step title="Configure the Craft filesystem">
    Log in to the Craft control panel and navigate to **Settings** > **Filesystems**. Create a filesystem or open the filesystem used by the required assets, then configure it:

    1. Enable **Files in this filesystem have public URLs**.
    2. In **Base URL**, enter a value that resolves to a stable absolute CDN URL — `https://cdn.example.com/uploads/`, an environment variable, or a dedicated alias such as `@cdn`.
    3. For a local filesystem, set **Base Path** to the matching server directory — `@webroot/uploads`.
    4. Save the filesystem.

    Craft supports environment variables and aliases in filesystem Base URL fields. Avoid the automatically determined `@web` alias, because its value can differ between sites. Craft documents these options in the [asset filesystem settings](https://craftcms.com/docs/5.x/reference/element-types/assets).
  </Step>

  <Step title="Attach an asset volume">
    Navigate to **Settings** > **Assets**. Create a volume or open an existing volume, attach it to the configured filesystem, and save the volume.

    When several volumes use the same filesystem, assign each one a unique, non-overlapping base path.

    A volume can store image transforms in a separate filesystem. Transformed images in that filesystem do not automatically use the CDN URL of the original assets. Configure the transform filesystem with public URLs and a **Base URL** that also resolves to the CDN domain. If the transform filesystem is left unchanged, this procedure covers only files stored in the selected filesystem.
  </Step>

  <Step title="Upload or select an asset">
    Navigate to **Assets**, select the configured volume, and upload a file. Existing assets in a volume attached to this filesystem use the new Base URL automatically.

    Replacing an asset at the same path can leave the previous file in the CDN cache. Enable Craft's [`revAssetUrls`](https://craftcms.com/docs/5.x/reference/config/general#revasseturls) setting so asset URLs change after a replacement, or [purge](/cdn/clear-cdn-resource-cache-by-url-pattern-or-all) the affected URL from Gcore.
  </Step>

  <Step title="Use the Craft-generated asset URL">
    In Craft templates, render the asset URL with `asset.url` or `asset.getUrl()`. Hardcoded origin URLs bypass the filesystem Base URL and must be replaced with Craft-generated URLs.
  </Step>

  <Step title="Verify CDN delivery">
    Open a page that contains the asset and use the browser developer tools:

    1. Open the **Network** panel.
    2. Reload the page.
    3. Select the asset request.
    4. Confirm that the request URL uses the CDN domain and returns a successful response.

    If the URL is empty, verify that public URLs are enabled and the filesystem has a Base URL. For a 404 response, compare the Base URL path, volume base path, and CDN origin path.
  </Step>
</Steps>