AWS Documentation » Amazon Simple Storage Service (S3) » Developer Guide » Hosting a Static Website on Amazon S3 » Configure a Bucket for Website Hosting	« Previous Next »
	Did this page help you? Yes \| No \| Tell us about it...

Configure a Bucket for Website Hosting

Topics

Overview

To configure a bucket for static website hosting, you add a website configuration to your bucket. The configuration includes the following information:

Index document
When you type a URL such as http://example.com you are not requesting a specific page. In this case the web server serves a default page, for the directory where the requested website content is stored. This default page is referred as index document, and most of the time it is named index.html. When you configure a bucket for website hosting, you must specify an index document. Amazon S3 returns this index document when requests are made to the root domain or any of the subfolders. For more information, see Index Documents and Folders .
Error document
If an error occurs, Amazon S3 returns an HTML error document. For 4XX class errors, you can optionally provide your own custom error document, in which you can provide additional guidance to your users. For more information, see Custom Error Document Support .
Redirects all requests
If you root domain is example.com and you want to serve requests for both http://example.com and http://www.example.com, you can create two buckets named example.com and www.example.com, maintain website content in only one bucket, say, example.com, and configure the other bucket to redirect all requests to the example.com bucket.
Advanced conditional redirects
You can conditionally route requests according to specific object key names or prefixes in the request, or according to the response code. For example, suppose that you delete or rename an object in your bucket. You can add a routing rule that redirects the request to another object. Suppose that you want to make a folder unavailable. You can add a routing rule to redirect the request to another page, which explains why the folder is no longer available. You can also add a routing rule to handle an error condition by routing requests that return the error to another domain, where the error will be processed.

You can manage your buckets website configuration using the Amazon S3 console. The bucket Properties panel in the console enables you to specify the website configuration.

To host a static website on Amazon S3, you need only provide the name of the index document.

To redirect all requests to the bucket's website endpoint to another host, you only need to provide host name.

However, when configuring bucket for website hosting, you can optionally specify advanced redirection rules.

You describe the rules using XML. The following section provides general syntax and examples of specifying redirection rules.

Syntax for Specifying Routing Rules

The following is a general syntax for defining the routing rules in a website configuration:

<RoutingRules> =
    <RoutingRules>
         <RoutingRule>...</RoutingRule>
         [<RoutingRule>...</RoutingRule>   
         ...]
    </RoutingRules>

<RoutingRule> =
   <RoutingRule>
      [ <Condition>...</Condition> ]
      <Redirect>...</Redirect>
   </RoutingRule>

<Condition> =
   <Condition> 
      [ <KeyPrefixEquals>...</KeyPrefixEquals> ]
      [ <HttpErrorCodeReturnedEquals>...</HttpErrorCodeReturnedEquals> ]
   </Condition>
    Note: <Condition> must has at least one child element.

<Redirect> =
   <Redirect> 
      [ <HostName>...</HostName> ]
      [ <Protocol>...</Protocol> ]
      [ <ReplaceKeyPrefixWith>...</ReplaceKeyPrefixWith>  ]
      [ <ReplaceKeyWith>...</ReplaceKeyWith> ]
      [ <HttpRedirectCode>...</HttpRedirectCode> ]
   </Redirect>
    Note: <Redirect> must has at least one child element. 
           Also, you can have either ReplaceKeyPrefix with or ReplaceKeyWith, 
           but not both.

The following table describes the elements in the routing rule.

Name	Description
`RoutingRules`	Container for a collection of RoutingRule elements.
`RoutingRule`	A rule that identifies a condition and the redirect that is applied when the condition is met. Condition: A `RoutingRules`, container must contain at least one routing rule.
`Condition`	Container for describing a condition that must be met for the specified redirect to be applied. If the routing rule does not include a condition, the rule is applied to all requests.
`KeyPrefixEquals`	The object key name prefix from which requests will be redirected. `KeyPrefixEquals` is required if `HttpErrorCodeReturnedEquals` is not specified. If both `KeyPrefixEquals` and `HttpErrorCodeReturnedEquals` are specified, both must be true for the condition to be met.
`HttpErrorCodeReturnedEquals`	The HTTP error code that must match for the the redirect to apply. In the event of an error, if the error code meets this value, then specified redirect applies. `HttpErrorCodeReturnedEquals` is required if `KeyPrefixEquals` is not specified. If both `KeyPrefixEquals` and `HttpErrorCodeReturnedEquals` are specified, both must be true for the condition to be met.
`Redirect`	Container element that provides instructions for redirecting the request. You can redirect requests to another host, or another page, or you can specify another protocol to use. A RoutingRule must have a `Redirect` element. A `Redirect` element must contain at least one of the following elements: `Protocol`, `HostName`, `ReplaceKeyPrefixWith`, `ReplaceKeywith` or `HttpRedirectCode`.
`Protocol`	The protocol, http or https, to be used in the Location header that is returned in the response. `Protocol` is not required if one of it's siblings is supplied.
`HostName`	The host name to be used in the Location header that is returned in the response. `HostName` is not required if one of it's siblings is supplied.
`ReplaceKeyPrefixWith`	The object key name prefix that will replace the value of `KeyPrefixEquals` in the redirect request. `ReplaceKeyPrefixWith` is not required if one of it's siblings is supplied. It can be supplied only if `ReplaceKeyWith` is not supplied.
`ReplaceKeyWith`	The object key to be used in the Location header that is returned in the response. `ReplaceKeyWith` is not required if one of it's siblings is supplied. It can be supplied only if `ReplaceKeyPrefixWith` is not supplied.
`HttpRedirectCode`	The HTTP redirect code to be used in the Location header that is returned in the response. `HttpRedirectCode` is not required if one of it's siblings is supplied.

The following are some of the examples:

Example 1: Redirect after renaming a key prefix

Suppose your bucket contained the following objects:

index.html

docs/article1.html

docs/article2.html

Now you decided to rename the folder from docs/ to documents/. After you make this change, you will need to redirect requests for prefix /docs to documents/. For example, request for docs/article1.html will need to be redirected to documents/article1.html.

In this case you add the following routing rule to the website configuration:

  <RoutingRules>
    <RoutingRule>
    <Condition>
      <KeyPrefixEquals>docs/</KeyPrefixEquals>
    </Condition>
    <Redirect>
      <ReplaceKeyPrefixWith>documents/</ReplaceKeyPrefixWith>
    </Redirect>
    </RoutingRule>
  </RoutingRules>

Example 2: Redirect requests for a deleted folder to a page

Suppose you delete the images/ folder (that is, you delete all objects with key prefix images/). You can add a routing rule that redirects requests for any object with the key prefix images/ to a page named folderdeleted.html.

  <RoutingRules>
    <RoutingRule>
    <Condition>
       <KeyPrefixEquals>images/</KeyPrefixEquals>
    </Condition>
    <Redirect>
      <ReplaceKeyWith>folderdeleted.html</ReplaceKeyWith>
    </Redirect>
    </RoutingRule>
  </RoutingRules>

Example 3: Redirect for an HTTP error

Suppose that when a requested object is not found, you want to redirect requests to an Amazon EC2 instance. You can add a redirection rule so that when an HTTP status code 404 (Not Found) is returned the site visitor is redirected to an EC2 instance that will handle the request. The following example also inserts the object key prefix report-404/ in the redirect. For example, if you request a page ExamplePage.html and it results in a HTTP 404 error, the request is redirected to a page report-404/ExamplePage.html on the specified EC2 instance. If there is no routing rule and the HTTP error 404 occurs, the error document specified in the configuration is returned.

  <RoutingRules>
    <RoutingRule>
    <Condition>
      <HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals >
    </Condition>
    <Redirect>
      <HostName>ec2-11-22-333-44.compute-1.amazonaws.com</HostName>
      <ReplaceKeyPrefixWith>report-404/</ReplaceKeyPrefixWith>
    </Redirect>
    </RoutingRule>
  </RoutingRules>

Document Conventions	« Previous Next »
Terms of Use	Did this page help you? Yes \| No \| Tell us about it...