How to configure static website hosting for an OSS on CloudBox bucket-Object Storage Service(OSS)-阿里云帮助中心

Static website hosting lets you serve a static website directly from an OSS on CloudBox bucket. Once enabled, the bucket serves your HTML, CSS, and JavaScript files using the bucket's endpoint as the website's domain.

Prerequisites

Before you begin, ensure that you have:

OSS on CloudBox available in one of the supported regions: China (Hangzhou), China (Shanghai), China (Shenzhen), China (Heyuan), China (Beijing), or China (Chengdu)
A cloud box purchased. For more information, see Purchase a cloud box
A Virtual Private Cloud (VPC) and a vSwitch created in the OSS on CloudBox. For more information, see Create a VPC and a vSwitch
A VPC internal network set up with a single tunnel configured for secure connection. To apply for this feature, contact technical support

How static website hosting works

When a browser requests a URL on your bucket's endpoint, OSS resolves the request using two special objects:

Default homepage (index.html): returned when a browser accesses the root domain or a URL ending with /. The object must exist in the root directory and allow anonymous access (ACL set to public-read). If the subfolder homepage feature is enabled, the object must also exist in each subdirectory that needs its own homepage.
Default 404 page (error.html): returned when OSS cannot find the requested object. The object must exist in the root directory and allow anonymous access (ACL set to public-read).

To set the ACL for these objects, see ACL settings.

Configuration example

The following bucket structure shows a typical setup after enabling static website hosting:

Bucket
 ├── index.html      ← default homepage (root)
 ├── error.html      ← default 404 page
 ├── example.txt
 └── subdir/
      └── index.html ← default homepage (subdirectory, required when subfolder homepage is enabled)

Set up static website hosting using the OSS console

Step 1: Configure static pages

Log on to the OSS console.
In the left-side navigation pane, choose Data Service > OSS on CloudBox Buckets. On the OSS on CloudBox Buckets page, click the target bucket.
In the left-side navigation pane, choose Data Management > Static Pages.

On the Static Pages tab, click Settings and configure the parameters based on your use case. Option A: Subfolder homepage disabled (recommended for simple sites) Use this option when you want all directory requests (URLs ending with /) to return the root-level homepage. Option B: Subfolder homepage enabled (for sites with directory structure) Use this option when each subdirectory has its own index.html, and you want requests to subdirectory URLs to serve that subdirectory's homepage. Subfolder 404 rule options The following example uses exampledir as the non-existent object at https://examplebucket.oss-cn-hangzhou.aliyuncs.com/exampledir.

Parameter	Description
Default homepage	The homepage OSS returns when a browser accesses the static website's domain name. Set to `index.html`.
Subfolder homepage	Select Disabled. Requests to the root domain or any URL ending with `/` return the root-level index page.
Default 404 page	The error page OSS returns when a browser requests a file that does not exist. Must be a file in the root directory. Set to `error.html`.
Error page status code	The HTTP status code for the error page response. Set to 404 or 200.

Parameter	Description
Default homepage	The homepage OSS returns when a browser accesses the static website's domain name. Set to `index.html`.
Subfolder homepage	Select Enabled. Requests to the root domain return the root-level index page. Requests to a URL ending with `/` return the index page of the corresponding directory. For example, accessing `https://examplebucket.oss-cn-hangzhou.aliyuncs.com/subdir/` returns `index.html` in the `subdir/` folder.
Subfolder 404 rule	Determines the response when a request targets a non-existent object. See the rule descriptions below this table.
Default 404 page	The error page OSS returns when a browser requests a file that does not exist. Must be a file in the root directory. Set to `error.html`.
Error page status code	The HTTP status code for the error page response. Set to 404 or 200.

Rule	Behavior
Redirect (default)	Checks if `exampledir/index.html` exists. If it does, returns a 302 redirect to `https://examplebucket.oss-cn-hangzhou.aliyuncs.com/exampledir/index.html`. If not, returns 404 and checks for `error.html`. If `error.html` also does not exist, returns a 404 status code.
NoSuchKey	Directly returns 404 and checks for `error.html`.
Index	Checks if `exampledir/index.html` exists. If it does, returns 200 with the file content. If not, checks for `error.html`.

Static page settings with subfolder homepage disabled

Static page settings with subfolder homepage enabled

Click Save.

Step 2: Upload the default homepage

Create a file named index.html with the following content:

   <html>
   <head>
       <title>My Website Home Page</title>
       <meta charset="utf-8">
   </head>
   <body>
     <p>Now hosted on OSS.</p>
   </body>
   </html>

Upload index.html to the root directory of examplebucket. Set the object ACL to public-read.
If the bucket contains subdirectories (such as subdir/), upload index.html to each subdirectory as well. Set the object ACL to public-read for each.

Step 3: Upload the default 404 page

Create a file named error.html with the following content:

   <html>
   <head>
       <title>Hello OSS!</title>
       <meta charset="utf-8">
   </head>
   <body>
     <p>This is error 404 page.</p>
   </body>
   </html>

Upload error.html to the root directory of examplebucket. Set the object ACL to public-read.

Set up static website hosting using an Alibaba Cloud SDK

Configure static website hosting with the Alibaba Cloud SDK for Java (version 3.15.0 or later). The example below sets index.html as the default homepage and error.html as the default 404 page.

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.SetBucketWebsiteRequest;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;

public class Demo {

    public static void main(String[] args) throws Exception {
        // Specify the data endpoint of the OSS on CloudBox bucket.
        String endpoint = "https://cb-f8z7yvzgwfkl9q0h****.cn-hangzhou.oss-cloudbox.aliyuncs.com";
        // Load access credentials from environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the bucket name.
        String bucketName = "examplebucket";
        // Specify the region where the bucket resides.
        String region = "cn-hangzhou";
        // Specify the CloudBox ID.
        String cloudBoxId = "cb-f8z7yvzgwfkl9q0h****";

        // Create an OSSClient instance. Call shutdown() when done to release resources.
        ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
        conf.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(new DefaultCredentialProvider(credentialsProvider.getCredentials()))
                .clientConfiguration(conf)
                .region(region)
                .cloudBoxId(cloudBoxId)
                .build();

        try {
            // Configure static website hosting.
            SetBucketWebsiteRequest request = new SetBucketWebsiteRequest(bucketName);
            request.setIndexDocument("index.html");   // Default homepage
            request.setErrorDocument("error.html");   // Default 404 page
            ossClient.setBucketWebsite(request);
        } catch (OSSException oe) {
            System.out.println("OSS error — the request reached OSS but was rejected.");
            System.out.println("Error Message: " + oe.getErrorMessage());
            System.out.println("Error Code:    " + oe.getErrorCode());
            System.out.println("Request ID:    " + oe.getRequestId());
            System.out.println("Host ID:       " + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Client error — failed to communicate with OSS.");
            System.out.println("Error Message: " + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Set up static website hosting using ossutil

For ossutil instructions, see put-bucket-website.

Set up static website hosting using the RESTful API

For custom integrations that require direct API calls, see PutBucketWebsite. Direct API calls require you to compute request signatures manually.

FAQ

Why is my subdirectory returning the root homepage instead of the subdirectory homepage?

The subfolder homepage feature must be enabled. In the Static Pages settings, set Subfolder homepage to Enabled and upload index.html to each subdirectory with ACL set to public-read.