Ghost Cloudflare R2 Storage Adapter

Cloudflare R2 storage adapter for Ghost.

Features

• Save images in Cloudflare R2
• Supports images, media and files
• Resize images to emulate Responsive Images
  • Implements saveRaw to force ghost to generate the srcset attribute for image cards
• Save images and media using UUID as name
• Compress resized images
• Written in TypeScript for maintainability

Installation

The adapter can be installed using npm or Docker.

Clone repo

# Starting from the Ghost base directory
mkdir -p content/adapters/storage
cd content/adapters/storage
git clone https://github.com/egeldenhuys/ghost-cloudflare-r2
cd ghost-cloudflare-r2
git checkout v0.1.1

Install using npm

Requires npm to be installed.

npm install
cp -f ./build/src/index.js ./build/src/index.js.map ./build/src/index.d.ts .

Install using Docker

Requires Docker to be installed. This has the advantage of not requiring you to pollute your server with node and npm if you are already using Docker.

./build-in-docker.sh

Configuration

The storage adapter makes use of the following environment variables:

Environment Variable	Description
GHOST_STORAGE_ADAPTER_R2_ENDPOINT	Cloudflare R2 Endpoint. Example: https://<account_id>.r2.cloudflarestorage.com
GHOST_STORAGE_ADAPTER_R2_ACCESS_KEY_ID	Access Key ID from Cloudflare R2 API Token
GHOST_STORAGE_ADAPTER_R2_SECRET_ACCESS_KEY	Secret Access Key from Cloudflare R2 API Token
GHOST_STORAGE_ADAPTER_R2_BUCKET	R2 Bucket to use for storage
GHOST_STORAGE_ADAPTER_R2_DOMAIN	R2 Custom domain to use for serving content
GHOST_STORAGE_ADAPTER_R2_UUID_NAME	Use UUID as name when storing images. May cause issues when used with Responsive Images. Default false. Allowed values true, false
GHOST_STORAGE_ADAPTER_R2_IMAGES_URL_PREFIX	URL prefix to use for storing and serving images from R2. Default /content/images/
GHOST_STORAGE_ADAPTER_R2_MEDIA_URL_PREFIX	URL prefix to use for storing and serving media (video) from R2. Default /content/media/
GHOST_STORAGE_ADAPTER_R2_FILES_URL_PREFIX	URL prefix to use for storing and serving files from R2. Default /content/files/
GHOST_STORAGE_ADAPTER_R2_CONTENT_PREFIX	Prefix to apply to all prefixes. Default empty. Must not contain a trailing slash. Example /blog_data
GHOST_STORAGE_ADAPTER_R2_GHOST_RESIZE	This needs to be set to false if Image resizing is disabled for Ghost ( env imageOptimization__resize). Default true
GHOST_STORAGE_ADAPTER_R2_RESPONSIVE_IMAGES	Generate an image for each width specified. Uses undocumented Ghost internal logic to get srcset generated. Default false. Allowed values true, false
GHOST_STORAGE_ADAPTER_R2_SAVE_ORIGINAL	Save the original unoptimized image. Only applicable if (env imageOptimization__resize) is set. Default true. Allowed Values true, false
GHOST_STORAGE_ADAPTER_R2_RESIZE_WIDTHS	Comma separated list of widths to resize the image when saving. This should match the srcset of your theme and any Ghost overrides. Default 300,600,1000,1600,400,750,960,1140,1200
GHOST_STORAGE_ADAPTER_R2_RESIZE_JPEG_QUALITY	Quality to use when resizing JPEG images. Default: 80
GHOST_STORAGE_ADAPTER_R2_LOG_LEVEL	Log level for the storage adapter. Default info. Allowed values debug, info, warn, error
GHOST_STORAGE_ADAPTER_R2_SAVE_ORIG_NAME_METADATA	Save the original file name in the object Metadata under the key original_name. Useful for correlating original images to images with UUID names. Default false. Allowed values true, false

All environment variables can also be used as keys in the JSON config. The following Ghost configuration is required to activate the plugin for images, media, and files: Alternatively they can be specified as environment variables (See docker-compose example below).

"storage": {
  "active": "ghost-cloudflare-r2",
  "ghost-cloudflare-r2": {
    "GHOST_STORAGE_ADAPTER_R2_ENDPOINT": "https://<account_id>.r2.cloudflarestorage.com"
    ...
  },
  "media": {
    "adapter": "ghost-cloudflare-r2",
    "storage_type_media": true
  },
  "files": {
    "adapter": "ghost-cloudflare-r2",
    "storage_type_files": true
  }
}

The section for media and files and be removed if the adapter should not handle those types. Note: this is an undocumented syntax and might change in future Ghost releases (tested on 5.30.1). See Configuring Storage Adapters for more details.

Redirects for backwards compatibility

If your blog is already live, and you have sent out newsletters with images, then you no longer have control over the image URLs in the emails. The URLs will be pointing to example.com/content/images/* but you want to serve them from the CDN cdn.example.com/content/images/*.

One solution is to use Ghost Redirects (assuming your content has been copied to the CDN):

# Temporary redirect if you might be changing the CDN in the future
302:
  ^\/content\/images\/(.*)$: https://cdn.example.com/content/images/$1
  ^\/content\/media\/(.*)$: https://cdn.example.com/content/media/$1
  ^\/content\/files\/(.*)$: https://cdn.example.com/content/files/$1

If you want the flexibility to later change to a different blog domain or CDN you can set GHOST_STORAGE_ADAPTER_R2_DOMAIN to blog.example.com and use Ghost to redirect old and new image requests to the CDN.

Example Docker Compose environment variables

environment:
  storage__active: ghost-cloudflare-r2
  storage__media__adapter: ghost-cloudflare-r2
  storage__media__storage_type_media: true
  storage__files__adapter: ghost-cloudflare-r2
  storage__files__storage_type_files: true
  GHOST_STORAGE_ADAPTER_R2_ENDPOINT: https://<account_id>.r2.cloudflarestorage.com
  GHOST_STORAGE_ADAPTER_R2_ACCESS_KEY_ID: xxxxxx
  GHOST_STORAGE_ADAPTER_R2_SECRET_ACCESS_KEY: xxxxxx
  GHOST_STORAGE_ADAPTER_R2_BUCKET: my-ghost-bucket
  GHOST_STORAGE_ADAPTER_R2_DOMAIN: https://cdn.example.com
  GHOST_STORAGE_ADAPTER_R2_UUID_NAME: false  # optional. Default: false
  GHOST_STORAGE_ADAPTER_R2_IMAGES_URL_PREFIX: /content/images/  # optional. Default: /content/images/
  GHOST_STORAGE_ADAPTER_R2_MEDIA_URL_PREFIX: /content/media/  # optional. Default: /content/media/
  GHOST_STORAGE_ADAPTER_R2_FILES_URL_PREFIX: /content/files/  # optional. Default: /content/files/
  GHOST_STORAGE_ADAPTER_R2_CONTENT_PREFIX: ''  # optional. Default: ''
  GHOST_STORAGE_ADAPTER_R2_GHOST_RESIZE: true  # optional. Default: true
  GHOST_STORAGE_ADAPTER_R2_RESPONSIVE_IMAGES: false  # optional. Default: false
  GHOST_STORAGE_ADAPTER_R2_SAVE_ORIGINAL: true  # optional. Default: true
  # Example widths to get Dawn theme working correctly:
  GHOST_STORAGE_ADAPTER_R2_RESIZE_WIDTHS: 300,600,1000,1600,400,750,960,1140,1200 # optional. Default: 300,600,1000,1600,400,750,960,1140,1200
  GHOST_STORAGE_ADAPTER_R2_RESIZE_JPEG_QUALITY: 80  # optional. Default: 80
  GHOST_STORAGE_ADAPTER_R2_LOG_LEVEL: info  # optional. Default: info
  GHOST_STORAGE_ADAPTER_R2_SAVE_ORIG_NAME_METADATA: false  # optional. Default: false

Testing

The tests require a S3 compatible endpoint. A docker-compose file for MinIO has been included to run a local instance for testing.

Also note that the tests will generate random images in /tmp.

The tests can be refactored and improved.