Building a Static Website

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.

ibmcloud cos bucket-create --bucket <bucketname>

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.

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.

http://<bucketname>.s3-web.<endpoint>/

Next steps

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