--- title: Configuring Amazon S3 related: - https://docs.kentico.com/13/custom-development/working-with-physical-files-using-the-api.md - https://docs.kentico.com/13/custom-development/working-with-physical-files-using-the-api/configuring-file-system-providers.md --- > Agent instructions: > **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown. > > - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version. > - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt). 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. > **Info:** **File name case** > > Unlike standard Windows file systems, the Amazon S3 storage is case-sensitive. To ensure consistent behavior, Xperience automatically converts all file and folder names to lower case when processing files on Amazon S3. ## 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. **MVC 5 development model.** Applies only when building with ASP.NET MVC 5. If this page also covers ASP.NET Core, that version is in its own block. Before you can begin mapping parts of the file system to Amazon storage, add the following keys to the _web.config_ files of both the MVC and administration applications: 1. Specify the ID of your Amazon access key: ```html ``` 2. Specify the Amazon access key: ```html ``` 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. ```html ``` **ASP.NET Core development model.** Applies only when building with ASP.NET Core. If this page also covers MVC 5, that version is in its own block. Before you can begin mapping parts of the file system to Amazon storage, add the following keys to the _web.config_ file of the administration application and the _appsettings.json_ file of the Core application: 1. Specify the ID of your Amazon access key: ```xml title="web.config" ``` ```js title="appsettings.json" "CMSAmazonAccessKeyID": "YourKey" ``` 2. Specify the Amazon access key: ```xml title="web.config" ``` ```js title="appsettings.json" "CMSAmazonAccessKey": "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. ```xml title="web.config" ``` ```js title="appsettings.json" "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 solution in Visual Studio (using the **WebApp.sln** file). 2. Create a [custom module class](https://docs.kentico.com/13/custom-development/creating-custom-modules/initializing-modules-to-run-custom-code.md). Add the class into a custom _Class Library_ project within the solution. > **Info:** 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. ```csharp 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 live site application (in addition to the Xperience administration project). > **Note:** **Additional website settings** > > When configuring this type of storage, keep in mind that the website itself must be configured to store files in the file system rather than in the database only. In **Settings -> System -> Files** enable the **Store files in file system** option. > > It is also recommended to enable **Redirect files to disk** in **Settings -> System -> Performance**. This means that files will be requested from the Amazon S3 account rather than from the database (if possible). Also, see the [Media library notes](#media-library-notes) at the end of this page for additional information about specifics of media libraries when using Amazon S3 storage. Additionally, you can configure the following optional settings. Note that the keys must be added to both the live site and administration applications: | Key | Description | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | CMSAmazonTempPath | Path to a local directory that the system uses to store temporary files.
**Default value**: \CMS\App\_Data\AmazonTemp
**Sample custom value**
` `
` "CMSAmazonTempPath": "C:\Windows\Temp" ` | | CMSAmazonCachePath | Path to a local directory where the provider stores cached files.
**Default value**: \CMS\App\_Data\AmazonCache
**Sample custom value**
` `
` "CMSAmazonCachePath": "C:\Cache" ` | | CMSAmazonEndPoint | Allows you to change the default URL of the Amazon S3 [Website Endpoint](http://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteEndpoints.html). For example, you can change the endpoint if you want to use CloudFront CDN.
**Default value**: http://.s3.amazonaws.com
**Sample custom value**
` `
` "CMSAmazonEndPoint": "http://someendpoint.s3.amazonaws.com" ` | | CMSAmazonRestApiEndPoint | Allows you to change the default URL of the Amazon S3 [REST API Endpoint](http://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteEndpoints.html#WebsiteRestEndpointDiff). The system uses the REST API to determine the region of buckets.
**Default value**:
**Sample custom value**
` `
` "CMSAmazonRestApiEndPoint": "http://s3.amazonaws.com" ` | | CMSAmazonPublicAccess | Specifies whether files uploaded to Amazon S3 through Xperience are accessible for public users.
**Default value**:
_true_ if you specify an endpoint
_false_ If no endpoint is specified
**Sample custom value**
`   `
` "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](https://aws.amazon.com/cloudfront/details/) to learn more. **MVC 5 development model.** Applies only when building with ASP.NET MVC 5. If this page also covers ASP.NET Core, that version is in its own block. To start using the Amazon CloudFront service with Xperience: 1. Create a **CloudFront Distribution**. You can use the [Amazon Management Console](https://console.aws.amazon.com). 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_ files of both the MVC and administration applications: ```xml ``` 4. Set the value of the **CMSAmazonEndPoint** key to the **Domain Name** URL of your created CDN. > **Note:** 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](https://developers.google.com/web/fundamentals/security/prevent-mixed-content/what-is-mixed-content?hl=en) warnings in your browser's console when retrieving files from the CDN. **ASP.NET Core development model.** Applies only when building with ASP.NET Core. If this page also covers MVC 5, that version is in its own block. To start using the Amazon CloudFront service with Xperience: 1. Create a **CloudFront Distribution**. You can use the [Amazon Management Console](https://console.aws.amazon.com). 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 of the administration application and the _appsettings.json_ file of your Core live site application: ```xml title="web.config" ``` ```js title="appsettings.json" "CMSAmazonPublicAccess": true, "CMSAmazonEndPoint": "EndpointURL" ``` 4. Set the value of the **CMSAmazonEndPoint** key to the **Domain Name** URL of your created CDN. > **Note:** 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](https://developers.google.com/web/fundamentals/security/prevent-mixed-content/what-is-mixed-content?hl=en) 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](https://docs.kentico.com/13/configuring-xperience/configuring-the-environment-for-content-editors/configuring-media-libraries.md#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](https://docs.kentico.com/13/deploying-websites/content-staging.md) 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.