Bucket Website Configuration Reference

A bucket website configuration is a set of files you can use as samples for your bucket website.

Indeed, a basic bucket website configuration contains at least an index and error HTML file, as well as a website configuration file.

While the index file (most commonly named index.html) is the default returned file when a user accesses the root of your domain, the error file (most commonly named error.html) is the file that is returned when an error occurs on your website.

However, the website configuration file, usually in JSON format, serves as a blueprint for how your bucket should behave when accessed as a website. In it, you can specify your index and error files as well as other configuration rules.

This page describes the elements you can specify in a bucket website configuration. Once you have written the necessary files, you need to apply them to your bucket. For more information, see Creating a Bucket Website.

Index and Error Files Samples

Those are samples, meaning they are intentionally kept basic for testing purposes.
Configuration sample for index.html
<!doctype html>
<html>
  <head>
    <title>My Bucket Website</title>
  </head>
  <body>
    <h1>Hi and welcome to my bucket website!</h1>
    <p>This website is static.</p>
  </body>
</html>
Configuration sample for error.html
<!doctype html>
<html>
  <head>
    <title>404</title>
  </head>
  <body>
    <h1>Oops!</h1>
    <p>Looks like something went wrong here.</p>
  </body>
</html>

Website Configuration Structure

Certain attributes are mutually exclusive when configuring a bucket for website hosting, meaning they cannot be used together:

  • RedirectAllRequestsTo and RoutingRules are incompatible. Indeed, the former is useful if you want all requests to the bucket to be redirected to a single hostname (effectively turning the entire bucket into a redirect) while the latter is used for more granular redirects based on specific conditions (like error codes or key prefixes).

  • Because RedirectAllRequestsTo redirects all requests to a specified domain, it is also naturally incompatible with having an IndexDocument and ErrorDocument.

Website Configuration Structure Using Redirections

Possible configuration structure for website.json
{
    "RedirectAllRequestsTo": {
        "HostName": "www.example.com",
        "Protocol": "https"
    }
}
Attribute Description

RedirectAllRequestsTo

When specified, all requests to the bucket are redirected to a specific hostname.

HostName

Specifies the domain name to which all traffic from the bucket is redirected, making it a global redirection setting.

Protocol

The protocol to use for the redirection. Possible values are http or https.

Website Configuration Structure Using Routing Rules

Possible configuration structure for website.json
{
    "IndexDocument": {
        "Suffix": "index.html"
    },
    "ErrorDocument": {
        "Key": "error.html"
    },
    "RoutingRules": [
        {
            "Condition": {
                "HttpErrorCodeReturnedEquals": "404",
                "KeyPrefixEquals": "old-content/"
            },
            "Redirect": {
                "HostName": "www.example.com",
                "HttpRedirectCode": "302",
                "Protocol": "https",
                "ReplaceKeyPrefixWith": "new-content/"
            }
        },
        {
            "Condition": {
                "HttpErrorCodeReturnedEquals": "404",
                "KeyPrefixEquals": "old-file.html"
            },
            "Redirect": {
                "HostName": "www.example.com",
                "HttpRedirectCode": "302",
                "Protocol": "https",
                "ReplaceKeyWith": "new-file.html"
            }
        }
    ]
}
Attribute Description

IndexDocument

Defines the default page serving as the index document for the bucket website.

Suffix

Specifies the file name of the index document, usually index.html.

ErrorDocument

Defines the returned error document when 4xx client errors occurs. A 4xx client error happens when the request either contains bad syntax or cannot be fulfilled.

Key

Specifies the file name of the error document, usually error.html.

RoutingRules

Defines the rules to redirect requests, under specific conditions.

Condition

Defines the condition under which the specified redirection is applied.

HttpErrorCodeReturnedEquals

The HTTP error code triggering the redirection. Commonly used codes include 404 (Not Found) or 403 (Forbidden).

KeyPrefixEquals

The prefix of the requested object key triggering the redirection in the bucket. This can be set to redirect requests for entire directories or specific files. For instance, using old-content/ will redirect all requests for objects within the old-content directory, while using old-file.html will specifically redirect requests to that file. This is particularly useful when setting up conditional redirects based on the structure of the stored objects.

Redirect

Specifies the redirect action that should be taken when the condition is met.

HostName

Specifies the domain name where requests are redirected based on specific conditions. This is useful for targeted redirection.

HttpRedirectCode

The HTTP status code to return for the redirection (301 for permanent redirection and 302 for temporary redirection).

Protocol

The protocol to use for the redirection. Possible values are http or https.

ReplaceKeyPrefixWith

Specifies the string to replace the key prefix matched by KeyPrefixEquals in the redirect request.

ReplaceKeyWith

Defines the specific key to use in the redirect request. This replaces the entire key matched by the condition.
Export to PDF