CKBox On-Premises CDN integration

This guide will walk you through the process of integrating a Content Delivery Network (CDN) into the CKBox On-Premises application. A CDN helps optimize content delivery by distributing it across multiple servers globally, reducing load times and enhancing user experience.

# CDN setup

# Prerequisites

In order to set the CDN for CKBox On-Premises ensure you have:

1. Access to a CDN provider account (e.g., AWS CloudFront, Cloudflare, etc.).
2. A custom domain linked to your CKBox On-Premises (e.g. https://yourdomain.com).

# Infrastructure setup

To set up CDN, first access your CDN provider’s dashboard, and create a new distribution (use web distribution or equivalent based on your provider).

After setting up the distribution, configure it to work with the CKBox On-Premises.

Set Origin Domain to your domain e.g. https://yourdomain.com which is linked to your On-Premises application.

After setting the origin domain you can optionally set custom domain names (CNAMEs) you want to use for the CDN e.g. cdn.yourdomain.com

Set the custom SSL Certificate if you have one, and apply changes to your distribution.

Depending on your CDN provider it may take some time for the distribution to become fully active.

# Define cache behaviors

In order to instruct CDN how to process specific requests, a cache behavior needs to be set. In your CDN provider dashboard navigate to Cache Behaviors Settings and choose Path Patterns. When CDN receives a viewer request, the requested path is compared with path patterns.

CKBox uses the following paths to serve optimized images that can be cached using CDN:

• /*/assets/*/file (this endpoint serves the contents of the original file asset with appropriate mime-type)
• /*/assets/*/images/* (this endpoint serves the responsive versions of images edited in CKEditor or embedded on the webpage)

Note: These specific paths are meant for caching to enhance performance for assets that do not frequently change. Caching dynamic or frequently updated content may result in stale data for users. Please note that only those two endpoints of CKBox On-Premises should be taken into account when defining caching paths.

# Set cache time

Cache time / Edge cache TTL is recommended to be 7 days. This gives the best tradeoff between performance and freshness of content. A longer cache reduces the need for repeated requests to the origin server, improving the response time. It also allows relatively fresh content, striking a balance between performance and ensuring users receive updated assets in a reasonable time frame. Finally, longer cache times can lead to cost savings as there are fewer requests to the origin server.

# Set assets origin

In order to redirect traffic through the CDN, the URLs to the images must point to the CDN’s domain. To set up the assets origin URL please set the ASSETS_ORIGIN environment variable while running the On-Premises docker container e.g.:

docker run --init -p 8080:8080 \
    -e LICENSE_KEY=[your license key from Customer Portal] \
    ...
    -e ASSETS_ORIGIN=[your CDN domain e.g. cdn.yourdomain.com] \

# Cache invalidation

Cache invalidation is currently supported in CKBox On-Premises only when using AWS CloudFront provider. Other CDN providers would require custom client implementation for CDN cache invalidation via CKBox Webooks.

To set up AWS CloudFront integration with CKBox On-Premises, set the required environment variables when running a docker container:

docker run --init -p 8080:8080 \
    -e LICENSE_KEY=[your license key from Customer Portal] \
    ...
    -e CDN_DRIVER="cloudfront" \
    -e CDN_REGION=[your AWS CloudFront region] \
    -e CDN_ACCESS_KEY_ID=[your AWS access key id] \
    -e CDN_SECRET_ACCESS_KEY=[your AWS secret key] \
    -e DISTRIBUTION_ID=[your distribution id] \

Assets invalidation happens specifically on asset overwrite. This can happen if the asset’s content is overwritten using POST:*/assets/{assetId} endpoint, or replaced while editing the image using CKBox image editor.