Host a static website in a bucket

A bucket can serve a static website: HTML, CSS, JavaScript, images and any other files that a browser reads as they are. In website mode, an address with no file name answers with the folder's index document, and a missing page answers with your error page or your app's own page. The site answers on the bucket's public URL and its custom domains.

A bucket runs no code of its own. For a site that needs a server, use App Deployment instead.

• Everything in Serve a bucket publicly.
• The site's files, built and ready to upload. Upload them with the dashboard (Upload, download and delete objects) or an S3 client (Upload the site).
• The public URL turned on, or a verified custom domain. Search engines do not index the public URL, so a site you want found needs a custom domain.

1. Open the service, select the Buckets tab, then select the bucket.
2. Select the Public access tab.
3. On the Website card, tick Serve as a website.
4. In Index document, keep index.html or type the key of your index page.
5. Choose what a missing page answers:
   • For a site of separate pages, type the key of your error page in Error document, such as 404.html. Leave it empty for a plain Not Found.
   • For a single page app (React, Vue, Svelte and the like) whose own router shows each page, tick Single page app.
6. Select Save website settings.

A message confirms it: Website settings saved. Saving purges what our edge cached for the bucket, so visitors see the new settings at once.

With website mode on, the bucket answers like this, here with the index document index.html and the error document 404.html:

When the error document or the index document is missing too, the answer is a plain Not Found with status 404. Everything else in What visitors can do still applies.

Keys are case sensitive, and a key is the whole path after the domain. docs/index.html is a different object from Docs/index.html.

An S3 client uploads a whole folder at once. With the AWS CLI and a profile for your access key (Connect an S3 client):

aws --profile coritan s3 sync ./dist s3://u7-site \
  --endpoint-url https://s3.fra.coritan.com:7337 --delete

--delete removes objects that are no longer in the folder. The AWS CLI sets each file's Content-Type from its extension, which is what browsers need to show a page or run a script.

After a deploy, purge the cache so visitors get the new files at once. Or give the HTML a short Cache-Control when you upload it, so our edge and browsers check for a new copy sooner:

aws --profile coritan s3 cp ./dist/index.html s3://u7-site/index.html \
  --endpoint-url https://s3.fra.coritan.com:7337 --cache-control "max-age=60"

Untick Serve as a website and select Save website settings. The message says Website mode off. Objects stay readable by their full key, and / answers 404 again.

/ answers Not Found

Website mode is off, or the bucket holds no object with the index document's key. Check Index document against the key in the object browser.

Enter the index document as an object key, such as index.html.

Type the key without a trailing /, and with no . or .. folder in it. A / at the start is dropped for you.

The single page fallback answers every missing path with the index document. Turn it off to use an error document.

A single page app cannot also have an error document. In the dashboard, ticking Single page app clears Error document for you.

The browser downloads a page instead of showing it

The object's Content-Type is wrong, such as application/octet-stream for an HTML file. Upload it again with --content-type "text/html", or with a client that sets the type from the extension.

A page that worked shows the old version

Purge the cache, then reload the page.

• Serve a bucket on your own domain
• Serve a bucket publicly
• Let websites use a bucket with CORS rules
• Static sites on App Deployment

PUT /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/website saves the website settings and answers with the whole public access view, as GET .../public does:

curl -X PUT https://api.coritan.com/api/v1/client/object-storage/1207/buckets/31/website \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "index": "index.html", "error": "404.html", "spa": false}'

enabled

Whether the bucket serves as a website.

index

The index document's key. Leave it out for index.html.

error

The error document's key, served with status 404. Leave it out, or send null, for a plain Not Found.

spa

Answer every missing key with the index document and status 200. It cannot be true while error is set.