Configuring Amazon S3

You can utilize the Amazon S3 storage service for storing your website files even though the website is hosted on-premise, on your own server.

Mapping files to Amazon storage

Mapping folders to Amazon storage allows you to store large files (e.g., media library files) on a shared storage and leverage Amazon’s Cloudfront CDN.

Before you can begin mapping parts of the file system to Amazon storage, you need to provide your credentials and bucket name to the system:

1. Specify the ID of your Amazon access key by inserting the following key:

   Copy

   
   
   
    <add key="CMSAmazonAccessKeyID" value="YourKey" />
   
   
    

2. Specify the Amazon access key by adding the following key:

   Copy

   
   
   
    <add key="CMSAmazonAccessKey" value="YourSecret" />
   
   
    

3. Add the following key to specify the bucket that you want to use to store files. Replace the value with the name of the bucket.

   Copy

   
   
   
    <add key="CMSAmazonBucketName"  value="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 solution in Visual Studio (using the WebApp.sln file).

2. Create a custom module class. Add the class into a custom Class Library project within the solution.

   For basic execution of initialization code, you only need to register a “code-only” module through the API. You do NOT need to create a new module within the Modules application in the administration interface.

3. Override the module’s OnInit method and perform the following:

   • Create a new instance of the Amazon S3 storage provider.
   • Specify the target bucket using the CustomRootPath property of the provider.
   • (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.
   • Map a directory to the provider. This is the directory that you want to store in the bucket.

using CMS;
using CMS.Base;
using CMS.DataEngine;
using CMS.IO;

// 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 a new StorageProvider instance for Amazon S3
        var mediaProvider = StorageProvider.CreateAmazonStorageProvider();

        // Specifies the target bucket
        mediaProvider.CustomRootPath = "mymediabucket";

        // Makes the bucket publicly accessible
        mediaProvider.PublicExternalFolderObject = true;

        // Maps a directory to the provider
        StorageHelper.MapStoragePath("~/MySite/Media/", mediaProvider);
    }
}

4. Save the file and Rebuild the solution.
5. Deploy the assembly containing the custom storage provider code to your separate MVC application (in addition to the Xperience administration project).

Also, see the Media library notes at the end of this page for additional information about specifics of media libraries when using Amazon S3 storage.

You can configure the following optional settings:

<add key="CMSAmazonTempPath" value="C:\Windows\Temp" />

<add key="CMSAmazonCachePath" value="C:\Cache" />

<add key="CMSAmazonEndPoint" value="http://someendpoint.s3.amazonaws.com" />

<add key="CMSAmazonRestApiEndPoint" value="http://s3.amazonaws.com" />

<add key="CMSAmazonPublicAccess" value="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 web.config file of your Xperience project.

3. Add the CMSAmazonPublicAccess and CMSAmazonEndPoint keys into the web.config file:

   Copy

   
   
   
    <appSettings>
        <add key="CMSAmazonPublicAccess" value="true" />
        <add key="CMSAmazonEndPoint" value="EndpointURL" />
    </appSettings>
   
   
    

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

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

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

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

Your project now starts using the created CDN service.

Media library notes

Using Amazon S3 storage for your project has some effects on media libraries.

Storing too many files in one media library folder

Storing a large number of media files in a single folder can significantly affect the performance of your project when editing the files in the Media library application. See Media library limitations when storing files in an external storage for details.

Use the same bucket when CMSAmazonPublicAccess is set to true

If all of the following conditions are true:

• you use Amazon S3 as external storage
• you set the CMSAmazonPublicAccess key to true
• you want to use content staging

then you need to use the same bucket across all instances in your staging topology. The system uses the bucket name in the URLs of media file links. If an instance in the staging topology uses a different bucket (via the CMSAmazonBucketName key), links to media files placed within staged content may not get resolved correctly.