Static Website Hosting

Scenarios

OBS allows static websites to be hosted by buckets and supports index page, error page, and page redirection. To host a static website in OBS, upload the static website files to a bucket, grant the read permission for these files to anonymous users, and configure static website hosting for the bucket.

Static websites contain static web pages and some scripts that can run on clients, such as JavaScript and Flash. Different from static websites, dynamic websites rely on servers to process scripts, such as PHP, JSP, and ASP.NET. OBS does not support scripts running on servers.

Figure 1 Static website hosting

After static website hosting is configured, you can access OBS in either of the following ways:

• Resource management mode: You can access OBS using a common domain name. You can use APIs or SDKs and default OBS domain names with endpoints contained to perform common operations on buckets and objects, such as upload, download, deletion, or listing.
• Static website: You can access objects in a bucket by using a specific domain name. You can configure domain name hosting rules to enable redirection of an index page, error page, or access page.

The configuration of static website hosting takes about two minutes to take effect. After it takes effect, you can access static resources using the following URLs:

https://static-website-domain-name/object-name
http://static-website-domain-name/object-name

A static website domain name is in the BucketName.obs-website.Endpoint format. BucketName indicates the name of a bucket, and Endpoint indicates the OBS domain name of the region where the bucket is located. For details about regions and endpoints, see Regions and Endpoints. For example, if you want to access bucket testbucket in the CN-Hong Kong region, the corresponding endpoint is ap-southeast-1.myhuaweicloud.com, and the static website domain name is testbucket.obs-website.ap-southeast-1.myhuaweicloud.com.

• Avoid using periods (.) in the target bucket name, or there may be errors when the client verifies the certificate during HTTPS access.
• In static website hosting scenarios, anonymous users must be granted access to hosted static website files. When they access the hosted files, there will be costs for outbound Internet traffic and requests.

To allow your users to access the content on your website, you must assign public read to your content. You can use bucket policies or ACLs on objects to grant permissions.

The following table lists the differences between the resource management mode and static website mode.

Precautions

For security and compliance purposes, Huawei Cloud OBS does not allow you to use static website hosting based on the default domain name (a bucket domain name or static website domain name). When you use such a domain name to access web pages in a browser, no content will be displayed. Instead, the content is downloaded as an attachment.

This restriction takes effect in different regions at the following two points in time:

January 1, 2022: CN North-Beijing1, CN North-Beijing4, CN East-Shanghai1, CN East-Shanghai2, and CN South-Guangzhou

March 25, 2022: CN-Hong Kong, AP-Bangkok, AP-Singapore, AF-Johannesburg, LA-Mexico City1, LA-Mexico City2, LA-Sao Paulo1, and LA-Santiago

You can still use static website hosting with a user-defined domain name. This way, the content can still be previewed. For details, see How Do I Preview OBS Objects in My Web Browser?

Configuring Static Website Hosting

Description

If you want to use a bucket to host static websites, add the website configuration to the bucket. The configuration includes the following information:

Index document

When you enter a URL such as http://example.com, you are not requesting a specific page. In this case, the web server will provide a default page that contains the directory of the requested website. This default page is called an index document, and in most cases it is known as index.html. When you configure a bucket for website hosting, you must specify an index document. When a request is sent to the root domain or any subfolder, OBS returns this index document.

Error document

If an error occurs, OBS returns an HTML error document. For 4XX errors, you can provide your own custom error document that gives users guidance to address the error.

Redirection of all requests

If the root domain is example.com and you need to respond to requests for http://example.com and http://www.example.com, you can create two buckets named example.com and www.example.com, respectively. Then you store the website content in only one bucket (such as example.com), and configure the other bucket to redirect all requests to the example.com bucket.

Redirection based on advanced conditions

You can redirect requests based on the specific object name or prefix in the request, or based on the response code. For example, if you deleted or renamed an object in a bucket, you can add a routing rule to redirect requests for this object to another object.

The syntax format is as follows:

<WebsiteConfiguration> 
    <IndexDocument> 
        <Suffix>index.html</Suffix></IndexDocument> 
    <ErrorDocument> 
        <Key>SomeErrorDocument.html</Key> 
    </ErrorDocument> 
    <RoutingRules> 
        ……RoutingRules……
    </RoutingRules> 
</WebsiteConfiguration>

Here is the syntax format of RoutingRules. The content in square brackets ([]) is optional.

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

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

<Condition> = 
    <Condition>  
        [ <KeyPrefixEquals>...</KeyPrefixEquals> ] 
        [ <HttpErrorCodeReturnedEquals>...</HttpErrorCodeReturnedEquals> ] 
    </Condition> 

<Redirect> = 
    <Redirect> 
        [ <HostName>...</HostName> ] 
        [ <Protocol>...</Protocol> ] 
        [ <ReplaceKeyPrefixWith>...</ReplaceKeyPrefixWith> ] 
        [ <ReplaceKeyWith>...</ReplaceKeyWith> ][ 
        <HttpRedirectCode>...</HttpRedirectCode> ] 
    </Redirect>

For website configuration for redirecting all requests and for setting routing rules, see the "Request Elements" area in Configuring Static Website Hosting for a Bucket

Examples:

Example 1: Modifying the object name prefix for redirection

Assume that your bucket contains the following objects:

index.html

docs/article1.html

docs/article2.html

You decide to change the object name from docs/ to documents/. After the modification, the request for an object with prefix /docs needs to be redirected to documents/. For example, the request for docs/article1.html needs to be redirected to documents/article1.html.

To meet this need, you can 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: Redirecting requests sent to deleted folders to a specified page

Assume that you have deleted the images/ folder, that is, you have deleted all objects whose object name prefix is images/. You can add a routing rule that redirects the requests of all objects whose prefix is images/ to a page named folderdeleted.html.

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

Example 3: Redirection when HTTP errors occur

You want to redirect requests for an object that is not found to www.example.com. You can add a routing rule to redirect users to www.example.com if HTTP status code 404 (object not found) is returned. The following example inserts the object name prefix report-404/ into Redirect. Assume you request the page ExamplePage.html and receive an HTTP 404 error. In this case, you will be redirected to the page report-404/ExamplePage.html on the www.example.com. If there is no routing rule and HTTP error 404 occurs, the error document specified in the configuration is returned.

<RoutingRules> 
    <RoutingRule> 
    <Condition> 
      <HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals > 
    </Condition> 
    <Redirect> 
      <HostName>www.example.com</HostName> 
      <ReplaceKeyPrefixWith>report-404/</ReplaceKeyPrefixWith> 
    </Redirect> 
    </RoutingRule> 
  </RoutingRules>

Index Document Support

An index document is a web page returned when a request is sent to the root of a website or any subfolder. For example, if the user enters http://www.example.com in the browser, the user is not requesting any specific page. In this case, OBS provides an index document, also known as a default page.

When configuring website hosting for your bucket, you must provide the name of an index document, which must be uploaded to OBS and configured with public read.

The trailing slash (/) in the root URL is optional. Both the following URLs can return an index document.

http://bucketname.obs-website.example.com/
http://bucketname.obs-website.example.com

In OBS, objects are stored in buckets horizontally, not in a hierarchical structure like that of a file system on a computer. You can create a logical hierarchy based on object names that represent a folder structure. For example, consider a bucket with the following three objects:

• sample1.jpg
• photos/2006/Jan/sample2.jpg
• photos/2006/Feb/sample3.jpg

Although they are not stored in a hierarchical structure, you can infer the following logical relationship from their object name.

• The sample1.jpg object is located at the root level of the bucket.
• The sample2.jpg object is located in the photos/2006/Jan subfolder.
• The sample3.jpg object is located in the photos/2006/Feb subfolder.

Custom Error Document Support

Table 1 lists the HTTP response codes returned by OBS when an error occurs.

Permissions Required for Website Access

When you configure a bucket as a website, you must configure public read for the objects in the bucket. To perform this operation, you need to write a bucket policy that grants the GetObject permission to everyone. If an object requested by a user does not exist on the website, OBS returns the HTTP response code 404 Not Found. If the object exists but you did not grant read permission for the object, OBS returns HTTP response code 403 Access Denied. Requesters can use the response code to determine whether the requested object exists. If you do not need this function, do not enable the bucket website support.

In static website hosting scenarios, anonymous users must be granted access to hosted static website files. When they access the hosted files, there will be costs for outbound Internet traffic and requests.

The following example bucket policy grants everyone the permission to access objects in a specified folder. For more information about bucket policies, see Bucket Policy.

{ 
   "Statement":[{ 
    "Sid":"PublicReadGetObject", 
      "Effect":"Allow", 
      "Principal": {"ID":"*"}, 
      "Action":["GetObject"], 
      "Resource":["example-bucket/*"  ] 
    } 
  ] 
}

A bucket policy applies only to objects owned by a bucket owner. If the bucket contains objects that are not owned by the bucket owner, use object ACLs to grant the public read permission for the objects.

You can use bucket policies or object ACLs to grant the public read permission for your objects. To use ACLs to grant the read permission to everyone, refer to the example below. You can add the authorization element to object ACLs. For details about ACL management, see ACLs.

<Grant> 
  <Grantee> 
    <Canned>Everyone</Canned> 
  </Grantee> 
  <Permission>READ</Permission> 
</Grant>

Related Functions

Prerequisites

Web page files required for static website hosting have been uploaded to the specified bucket.

The static website files hosted in the bucket are accessible to all users.

Static web page files in the Archiveor Deep Archive storage class have been restored. For more information, see Restoring Archive or Deep Archive Objects.

Ways to Configure Static Website Hosting

You can use OBS Console, APIs, or SDKs to configure static website hosting.