Static Website Hosting

Step 1: Configure static website hosting

Configure a default homepage and an error page to set up basic access rules. This ensures users can browse your site and receive a helpful error message when an error occurs.

1. Go to the Buckets page, click the name of the target bucket, and then in the left-side navigation pane, click Data Management > Static Page.

2. Click Settings and configure the following parameters:

   • Default Homepage: Set to index.html.

   • Subfolder Homepage: Choose whether to enable a separate homepage for subfolders based on your website's structure.

     • Disabled (Default): Suitable for simple websites that do not require separate homepages for subfolders. With this option, any URL path that ends with a forward slash (/) returns the default homepage from the root directory.

     • Enabled: Suitable for complex websites with multiple independent content sections, such as /blog/ or /docs/, where each section has its own homepage. When enabled, you must also configure the Subfolder 404 Rule to define how the system responds when a user requests a file that does not exist:

       • Redirect (Default): Redirects to the directory URL. If a requested file does not exist, the system checks for a homepage in the corresponding directory. If one exists, the system returns a 302 redirect response, and the browser's address bar updates to the directory path. For example, .../subdir changes to .../subdir/.

       • Index: Returns homepage content directly. Similar to Redirect, but if a homepage is found, the system returns its content with a 200 status code. The browser's address bar remains unchanged.

       • NoSuchKey: Returns a 404 error directly. This is the strictest rule. If a requested file does not exist, the system returns a 404 error, regardless of whether a homepage exists in the corresponding directory.

         Subfolder 404 rule

         When the subfolder homepage feature is enabled, this rule defines the system's response to requests for a non-existent object, ensuring your website's routes are handled correctly.

         Core mechanism: Object vs. directory requests

         The rule's behavior depends on the URL structure, specifically whether it ends with a forward slash (/):

         • Object request: The URL does not end with /, such as .../subdir. The system interprets this as a request for an object named subdir.

         • Directory request: The URL ends with /, such as .../subdir/. The system interprets this as a request for the default homepage in the subdir directory.

         The subfolder 404 rule is triggered only when an object request fails (that is, the object does not exist).

         Rule behavior

         The following table explains the behavior of each rule when a request is made for an object that does not exist, such as http://example.com/subdir.

         Rule	Core behavior	Processing flow	Final result (depends on whether subdir/index.html exists)
         Redirect (Default)	Redirects to directory URL: The system checks for a homepage in the corresponding directory. If found, it returns a 302 redirect response.	The subdir object is not found, which triggers the rule. The system checks whether subdir/index.html exists. If it exists, a 302 Found response is returned with the Location header pointing to .../subdir/. If not, a 404 Not Found response is returned.	If it exists: The homepage content is displayed, and the browser address bar updates to .../subdir/. If it does not exist: The 404 error page is displayed.
         Index	Returns homepage content directly: The system checks for a homepage in the corresponding directory. If found, it returns the content with a 200 status code.	The subdir object is not found, which triggers the rule. The system checks whether subdir/index.html exists. If it exists, the file content and a 200 OK status are returned. If not, a 404 Not Found response is returned.	If it exists: The homepage content is displayed, and the browser address bar remains .../subdir. If it does not exist: The 404 error page is displayed.
         NoSuchKey	Returns a 404 error directly: The system does not perform any additional directory or homepage checks.	The subdir object is not found, which triggers the rule. A 404 Not Found response is returned immediately.	Regardless of whether it exists: Always returns a 404 error page.

   • Default 404 Page: Set to error.html.

   • Error Page Status Code: Select 404.

3. Click Save.

Step 2: Upload website files

Upload your prepared HTML files to the bucket to provide content for your website.

1. Download and extract the sample file html.zip, or use your own project files.

2. In the left-side navigation pane, click Object Management > Objects.

3. Drag the sample files or your existing project files to the upload window. After the files are added to the list, click Upload Object.

Step 3: Set bucket permissions

Configure public read permissions to make your website content accessible to internet users.

1. The Block Public Access feature is enabled by default when you create an OSS bucket. This feature prevents you from setting the bucket's access control list (ACL) to public-read or public-read-write. You must disable this feature first.

   1. In the left-side navigation pane, click Permission Control > Block Public Access.

   2. Click the Block Public Access toggle. In the dialog box that appears, enter I confirm that I want to disable Block Public Access, and then click OK.

2. Set the bucket's access permissions to public-read.

   1. Go to the Access Control List tab and click Set.

   2. Set Bucket ACL to Public Read. In the dialog box that appears, click Continue.

   3. Click Save.

Step 4: Verify the website configuration

Test your website to confirm that the static website hosting feature is working correctly.

• Verify homepage access: In a browser, go to your custom domain name, for example, http://example.com, to view the result.

  If the page displays the default homepage for OSS static website hosting, titled Welcome to OSS with the subtitle This is a static homepage, and has three buttons (Product Details, Product Console, and Product Documentation) at the bottom, your static website hosting configuration is working.

• Verify the 404 page: In a browser, try to access a file that does not exist, for example, http://example.com/missing-object.

  If the page displays the title Welcome to OSS and the message This is a 404 page, your 404 error page is configured correctly.

Step 1: Configure SPA hosting

Configure the hosting parameters to optimize for an SPA's routing features and ensure that client-side routing works correctly.

1. Go to the Buckets page, click the name of the target bucket, and then in the left-side navigation pane, click Data Management > Static Page.

2. Click Settings and configure the following parameters:

   • Default Homepage: Set to index.html.

   • Subfolder Homepage: Select Disabled. With this setting, any request to the static website domain or any URL under that domain ending with a forward slash (/) returns the root directory's default homepage.

   • Default 404 Page: Set to index.html (critical configuration: redirects all routes to the application entry point).

   • Error Page Status Code: Select 200 (ensures that route transitions return the correct status code).

3. Click Save.

Step 2: Upload application files

Upload your prepared SPA files to the bucket to complete the application deployment.

1. Download and extract the sample application demo.zip, or use your own application files.

2. In the left-side navigation pane, click Object Management > Objects.

3. Drag all files from the demo directory or your own application files to the upload window. After all files are added to the list, click Upload Object.

Step 3: Set bucket permissions

Configure public access permissions so that your SPA is accessible to users.

1. Disable Block Public Access for the bucket.

   1. In the left-side navigation pane, click Permission Control > Block Public Access.

   2. Click the Block Public Access toggle. In the dialog box that appears, enter I confirm that I want to disable Block Public Access, and then click OK.

2. Set the bucket's access permissions to public-read.

   1. Go to the Access Control List tab and click Set.

   2. Set Bucket ACL to Public Read. In the dialog box that appears, click Continue.

   3. Click Save.

Step 4: Verify application deployment

Test your website to confirm that the SPA is deployed successfully and can handle route transitions.

• Verify homepage access: In a browser, go to your custom domain name (for example, http://example.com) to access the SPA. The result is shown in the following figure.

  

• Verify the 404 behavior: In a browser, try to access a file that does not exist, for example, http://example.com/missing-object. The request is redirected to the application's entry point, and a 200 OK status code is returned.

Best practices

• Secure transport: Enable HTTPS access

  Modern browsers display "not secure" warnings for HTTP websites, and search engines give higher SEO rankings to HTTPS sites. You should enforce HTTPS access for your custom domain name by following the guide to access OSS over HTTPS. The HTTPS protocol uses TLS/SSL to encrypt data in transit, which prevents data from being stolen or tampered with and improves website security and user trust.

• Performance optimization: Configure CDN acceleration

  If your static website serves a global audience or receives high-concurrency traffic, you can configure CDN acceleration. This caches your content on edge nodes around the world, which significantly improves access speed and reduces your OSS traffic costs.

• Cross-origin resource sharing (CORS): Configure CORS rules

  Single-page applications often need to call backend APIs or access third-party resources, which can be restricted by a browser's same-origin policy. By configuring cross-origin resource sharing (CORS) rules, you can specify allowed origins, methods, and headers to ensure your application can access the necessary API services and external resources.

• Version management: Implement releases and rollbacks

  A production environment requires the ability to release new versions quickly and perform emergency rollbacks. Enable the OSS versioning feature and integrate it with automation tools like Jenkins to create a full CI/CD workflow. This improves release efficiency and system stability.

Risk mitigation

• Bandwidth theft prevention: Configure hotlink protection

  When other websites directly link to your static resources, it can lead to extra traffic costs and server load. By configuring Referer-based hotlink protection, you can create a whitelist of allowed domains. This effectively prevents unauthorized websites from using your bandwidth and helps control costs.

• Access monitoring: Enable access logs

  Production environments require complete access records for security audits, performance analysis, and troubleshooting. Enable real-time log query to record detailed information for all access requests. This helps you identify unusual access patterns, analyze user behavior, and optimize website performance.

404 error on SPA page refresh

In a single-page application, all routes are handled by client-side JavaScript. When you directly access or refresh a non-root route, the server cannot find a corresponding physical file. To solve this, set the Default 404 Page to index.html and the Error Page Status Code to 200. This configuration redirects all "not found" paths to the application's entry point, allowing the client-side router to handle them correctly.

Disabling static website hosting

1. Go to the Buckets page, click the name of the target bucket, and then in the left-side navigation pane, click Data Management > Static Page.

2. Click Settings, clear the Default Homepage and Default 404 Page settings, and then click Save to disable the static website hosting feature.

Support for dynamic content

Static website hosting supports only static files, such as HTML, CSS, and JavaScript. It does not support server-side dynamic languages like PHP, Python, or Java. If you need dynamic functionality, you can use client-side rendering with a frontend framework or call backend APIs by using serverless services like Function Compute.