How to setup a custom assets domain

If you want to use your own domain for assets instead of the default domain a.storyblok.com you can use a Cloudfront distribution to forward requests to Storyblok’s origin servers.

The following tutorial shows the how you can setup your own domain for Storyblok’s assets using Amazon AWS. If you don’t have a Amazon AWS account yet signup here.

1. Create a SSL certificate

Create a SSL certificate for your domain using AWS Certificate Manager in the region us-east-1 (N. Virginia). It's important that you create the certificate in us-east-1 because CloudFront only accepts certificates from this region.

aws certificate manager interface

2. Create a CloudFront distribution

Create a CloudFront distribution and defining following settings:

  • Origin Domain Name: a.storyblok.com

  • Compress Objects Automatically: Yes

  • Alternate Domain Names (CNAMEs): assets.yourdomain.com

  • SSL Certificate: Custom SSL Certificate (Choose your certificate)

Leave the default value for the rest of the settings, except for the cache behavior that will require some work.

aws cloudfront interface

Since the image service is using the accept header to determine if the client supports the webp format, you need to forward that header to the origin.
To achieve that you can proceed in 2 ways: a cache policy or the legacy settings.


The first approach is to create a new cache policy on AWS that will forward the accept header.
Create a new policy with the following settings:

  • Headers: Include the following headers and add Accept to the list of the headers.

aws new cache policy

Inside the settings of the distribution in the Cache key and origin requests area, you can select Cache policy and origin request policy and select your newly created policy from the list.

distribution creation

Another approach is to use the legacy cache settings, and for this, you don't need to create a new policy.
From the headers dropdown, select Include the following headers and add accept to the list.

aws cache legacy settings

3. Restrict access to a space (optional)

The CloudFront distribution will be able to deliver assets from any space. In case you want to restrict the distribution to a specific space you can do so by filling out the Origin Path field in the Origin Settings with the value /f/YOURSPACEID.

4. Point your domain to CF

After the CloudFront distribution has been created and has the status active change your DNS settings of your domain to point to YOURID.cloudfront.com.

5. Replace the domain in your app

Create a helper that replaces the default domain of an image field URL with your new custom domain.

Example in Javascript:

function img(src) {

  return (src || '').replace('//a.storyblok.com', '//assets.yourdomain.com')

}

If you restricted the access to a specific space as in step #3 you can refer to the example below:

function img(src) {

  return (src || '').replace('//a.storyblok.com/f/YOURSPACEID', '//assets.yourdomain.com')

}

How to limit access to multiple spaces

You can limit access from your CloudFront distribution to a list of spaces just by changing slightly the setup. Please, perform step #1 of the instructions above as first and step #5 as last also in this process.

1. Create a CloudFront distribution

Create a CloudFront distribution using the following settings:

  • Origin Domain Name: yourdomain.com

  • Compress Objects Automatically: Yes

  • Alternate Domain Names (CNAMEs): assets.yourdomain.com

  • Origin Protocol Policy: HTTPS Only or Match Viewer

  • SSL Certificate: Custom SSL Certificate (Choose your certificate)

Leave the default value for the other fields.

Creation of a new CloudFront distribution

2. Create a new origin for Storyblok

Create a new origin with the following settings:

  • Origin Domain Name: a.storyblok.com.s3.amazonaws.com

Leave the default value for the other fields.

new cloudfront distribution origin

3. Create a new behavior

Create a new behaviour with the following settings:

  • Path Pattern: f/YOUR-SPACE-ID/*

  • Origin or Origin Group: S3-a.storyblok.com (the origin you created in step #2)

  • Compress Objects Automatically: Yes

Leave the default value for the other fields.

If you want to add assets from more spaces, you just have to repeat this step for each new one.

new cloudfront behaviour

In the list of behaviors, move the newly created one(s) at the top of the list.

list of cloudfront behaviours

This way you will be able to display asset from f/YOUR-SPACE-ID (for each space you added) only and any other URL outside of that path will return the 404 page from your domain.