Amazon S3

Xperience by Kentico supports file system providers that allow you to map parts of the file system to Amazon S3 storage. You can use Amazon S3 when:

• deploying self-managed projects
• you wish to store parts of the application file system (e.g., media library files) in a shared storage

Media library files in Amazon S3

Media library files stored in Amazon S3 have the following limitations:

• Storing a large number (thousands) of media library files in a single media library can significantly affect the performance and user experience of the Media libraries application.
  • We recommend structuring media library files into multiple media libraries and storing at most 100 files in a single media library folder.
• Mapping subfolders of media libraries is not supported. You can map either the directory containing the media libraries (~/assets/media), or individual media libraries (~/assets/media/<MediaLibraryName>).
• The system’s automatic clearing of files from the server-side cache does not work for files stored in an external storage. If you modify a media file, the website may still display the old version until the cache expires (unless you manually clear the application’s cache). See also: File caching.

Map files to Amazon storage

Mapping folders to Amazon storage allows you to store files on a shared storage and leverage Amazon’s Cloudfront CDN.

Before you can map parts of the file system to Amazon storage, add the following application settings to your project:

1. The ID of your Amazon access key:

   appsettings.json

   Copy

   
   
    "CMSAmazonAccessKeyID": "YourKey"
   
    

2. The Amazon access key:

   appsettings.json

   Copy

   
   
    "CMSAmazonAccessKey": "YourSecret"
   
    

3. Add the following key to specify the bucket that you want to use to store files.

   appsettings.json

   Copy

   
   
    "CMSAmazonBucketName": "YourBucketName"
   
    

With the Amazon account connected and configured, use the following process to map parts of the file system to the specified bucket:

1. Open the Xperience project in Visual Studio.

2. Add a custom Class Library project and install the Kentico.Xperience.AmazonStorage NuGet package as a dependency.

3. Create a custom module class in the created library.

4. Override the module’s OnInit method and for each folder that you want to store in the shared storage:

   1. Create a new instance of the Amazon S3 storage provider.

   2. Specify the target bucket using the CustomRootPathproperty of the provider.

   3. (Optional) You can specify whether you want the bucket to be publicly accessible using the PublicExternalFolderObject property of the provider. True means the bucket is publicly accessible.

   4. Map the directory to the provider:

      As some deployment environments don’t provide a persistent file system, we recommend mapping the following project folders to prevent a possible loss of files due to redeployment, swapping of slots, etc.:

      • ~/assets/ – contains content item assets and media libraries
      • ~/BizFormFiles/ – contains files uploaded from users using the Upload file form component
      Mapping assets and form files to Amazon storage

      Copy

      
      
       /* The following code snippet demonstrates the recommended mappings 
       for the **~/assets/** and **~/BizFormFiles/** folders mentioned 
       in the note above. You can use the same approach to also map 
       other folders from your project's file system.*/
      
       using CMS;
       using CMS.DataEngine;
       using CMS.IO;
      
       using Kentico.Xperience.AmazonStorage;
      
       // Registers the custom module into the system
       [assembly: RegisterModule(typeof(CustomInitializationModule))]
      
       public class CustomInitializationModule : Module
       {
           // Module class constructor, the system registers the module under the name "CustomInit"
           public CustomInitializationModule()
               : base("CustomInit")
           {
           }
      
           // Contains initialization code that is executed when the application starts
           protected override void OnInit()
           {
               base.OnInit();
      
               // Creates new StorageProvider instances for Amazon S3
               var assetsProvider = AmazonStorageProvider.Create();
               var formFilesProvider = AmazonStorageProvider.Create();
      
               // Specifies the target buckets, the providers ensure their existence in the storage account
               assetsProvider.CustomRootPath = "myassetsbucket";
               formFilesProvider.CustomRootPath = "myformfilesbucket";
      
               // Makes the 'myassetscontainer' container publicly accessible
               assetsProvider.PublicExternalFolderObject = true;
      
               // Makes the 'myformfilescontainer' container not publicly accessible
               formFilesProvider.PublicExternalFolderObject = false;
      
               // Maps the local directories to the storage providers
               StorageHelper.MapStoragePath("~/assets", assetsProvider);
               StorageHelper.MapStoragePath("~/BizFormFiles", formFilesProvider);    
           }
       }
      
       

The deployed application now stores files from the ~/assets and ~/BizFormFiles/ project folders in the myassetsbucket and myformfilesbucket Amazon S3 buckets.

Optional application settings for Amazon S3

"CMSAmazonTempPath": "C:\\Windows\\Temp"

"CMSAmazonCachePath": "C:\\Cache"

"CMSAmazonEndPoint": "http://someendpoint.s3.amazonaws.com"

"CMSAmazonRestApiEndPoint": "http://s3.amazonaws.com"

"CMSAmazonPublicAccess": true

Configuring Xperience to use Amazon CloudFront CDN

A Content Delivery Network (CDN) speeds up distribution of content to the end users through a network of data centers. See Amazon CloudFront Product Details to learn more.

To start using the Amazon CloudFront service with Xperience:

1. Create a CloudFront Distribution. You can use the Amazon Management Console. Select your Amazon S3 storage bucket as the Origin Domain Name.

2. Edit the application settings file of your Xperience project and add the CMSAmazonPublicAccess and CMSAmazonEndPoint keys:

   appsettings.json

   Copy

   
   
    "CMSAmazonPublicAccess": true,
    "CMSAmazonEndPoint": "EndpointURL"
   
    

3. Set the value of the CMSAmazonEndPoint key to the Domain Name URL of your created CDN.

   If your website runs under HTTPS, we recommend always specifying the endpoint URL with the HTTPS protocol as well.

   For example: https://domain.cloudfront.net

   Without this configuration you may receive Mixed Content warnings in your browser’s console when retrieving files from the CDN.

Your project now uses the created CDN service.