IBM Cloud Docs
Building a Static Website

Building a Static Website

This tutorial shows how to host a static website on IBM Cloud® Object Storage, including creating a bucket, uploading content, and configuring your new website.

Hosting static websites with IBM Cloud Object Storage serves static content for public access giving users flexibility, ease of delivery, and high availability. This tutorial contains instructions for using cURL, the AWS CLI, as well as the Console. Choose your path for this tutorial by using the links for switching between the instructions above the title of this topic.

The Scenario

The scenario for this tutorial simplifies web hosting to its essentials to highlight the steps involved. While not every configuration option will be covered in this tutorial, correctly completing this tutorial results in web-accessible content.

Before you start

Ensure that you have what you need to start:

  • An account for the IBM Cloud Platform
  • An instance of IBM Cloud Object Storage
  • Content in fixed form, like text (HTML would be perfect), and image files

Check that you have the access as appropriate to either the instance of IBM Cloud Object Storage you will be using or the proper permissions for the buckets you will be using for this tutorial.

For use of the IBM Cloud CLI with this tutorial, you will need to configure the Object Storage plug-in to specify the service instance you want to use and the default region where you want your new bucket to be created.

Create a bucket configured for public access

Creating a bucket for a static website will require public access. There are a number of options for configuring public access. Specifically, using the ObjectReader IAM role will prevent the listing of the contents of the bucket while still allowing for the static content to be viewed on the internet. If you want to allow the viewing of the listing of the contents, use the ContentReader IAM role for your bucket.

Create a bucket

After configuring the CLI plug-in, replace the placeholder content as shown in the example command to create a bucket:

ibmcloud cos bucket-create --bucket <bucketname>

Once you login to the Console and after you create an instance of IBM Cloud Object Storage, you can create a bucket. Click on the button labeled "Create bucket" and choose from the options as shown in Figure 1. Select the card that reads "Customize your bucket."

Customize your bucket

The container for the static files in your website will reside in a bucket that you can name. The name you create must be unique, should not contain personal or identifying information, can't have two periods, dots, or hyphens in a row, and must start and end with alphanumeric characters (ASCII character set items 3–63). See Figure 2 for an example.

Name bucket for Static Website

Setting public access

In all scenarios for this tutorial, you will want to use the UI at the Console to allow public access to your new website.

When creating a bucket for hosting Static Website content, there is an option to enable public access as part of the bucket creation process. See Figure 3 for the option to enable public access to your bucket. For the explanation of the options for the "index document" and "error document" as shown, find more below in the section Configure the options for your website. You may complete the basic configuration with this step, before uploading content to your bucket as shown in the next step.

Enable public access

Upload content to your bucket

The content of your hosted static website files focuses naturally on information and media. A popular approach to creating content for static websites are open source generators listed at StaticGen. For the purpose of this tutorial, we only need two files:

  • An index page, typically written in HTML and named index.html, that loads by default for visitors to your site
  • An error page, also in HTML and here named error.html; typically the error page is loaded when a visitor tries to access an object that isn't present or doesn't have public access

Other files, like images, PDFs, or videos, can also be uploaded to your bucket (but this tutorial will focus only on a minimum set of requirements).

For the purpose of this tutorial, place the HTML pages for the index and error handling in a local directory. Replace the placeholder content as shown in the example command to upload your html files:

ibmcloud cos object-put --bucket BUCKET_NAME --key KEY [--body FILE_PATH]

You may have already completed the basic configuration for hosting your static website. Files can be uploaded directly in the Console once you've named and configured your bucket. Note the step is optional as shown in Figure 4, and can occur at any point before the testing of your new hosted website.

Upload files

For the rest of the tutorial, we will assume that the object key for the index page is index.html and the key for the error document is error.html although any appropriate filename can be used for the suffix or key.

Configure the options for your website

There are more options than this tutorial can describe, and for the purpose of this tutorial we only need to set the configuration to start using the static website feature.

Create a JSON file with the appropriate configuration information:

  "ErrorDocument": {
    "Key": "error.html"
  "IndexDocument": {
    "Suffix": "index.html"

Replace the placeholder content as shown in the example command to configure the website:

ibmcloud cos bucket-website-put --bucket BUCKET_NAME --website-configuration file://<filename.json>

You may have completed this step during the creation of your bucket, as the basic configuration for your hosted static website determines when and how content is shown. For visitors to your website who fail to provide a key, or web page, the default file will be shown instead. When your users encounter an error, the key for the error page determines what content visitors will receive. The configuration options for the default and error pages are repeated for reference.

Configure options

Testing and visiting your new website

Once you have configured your bucket to provide HTTP headers using the example command, all you have to do to test your new site is visit the URL for the site. Please note the protocol shown (http), after replacing the placeholders with your own choices made previously in this tutorial:


With the successful testing of your new site, you can now explore more options and add more content.

Next steps

The detailed description of configuration options for IBM Cloud Object Storage hosted static websites can be found in the API Documentation.