Hosting static websites on S3

Introduction

Any S3 bucket can be used to host a static website (HTML, CSS, JavaScript, images) that is publicly accessible via HTTPS. You do not need a web server — simply upload the files and enable website mode on the bucket.

Two addresses are used:

Address

What is it used for?

‘https://s3-2.atman.pl’

S3 API: creating a bucket, uploading files, configuration (AWS CLI, SDK, rclone)

https://<bucket-name>.s3-2website.atman.pl/

Website address for visitors

Example: the “my-site” bucket will be accessible at https://moja-strona.s3-2website.atman.pl/.

The bucket name is part of the address, so it must comply with DNS naming conventions: lowercase letters, numbers and hyphens only, no full stops (full stops invalidate the HTTPS certificate).

The hosting service supports static content only. Server-side code (PHP, Python, databases) will not be executed.

A step-by-step guide to launching a website

The examples use the AWS CLI with a user profile that has permissions for the bucket. You must set the following variables:

export AWS_PROFILE=moj-profil
export EP=https://s3-2.atman.pl
export BUCKET=moja-strona

1. Creating a bucket

aws --endpoint-url $EP s3 mb s3://$BUCKET

2. Uploading website files

The ./public directory should contain at least index.html (the home page) and, optionally, error.html (the 404 error page).

All you need for the test are two simple files:

public/index.html
<!doctype html>
<html lang="pl">
<head>
  <meta charset="utf-8">
  <title>Moja strona</title>
</head>
<body>
  <h1>Strona działa!</h1>
  <p>Ta strona jest serwowana z bucketa S3.</p>
</body>
</html>

public/error.html
<!doctype html>
<html lang="pl">
<head>
  <meta charset="utf-8">
  <title>404</title>
</head>
<body>
  <h1>404 – Nie znaleziono strony</h1>
  <p><a href="/">Wróć na stronę główną</a></p>
</body>
</html>
aws --endpoint-url $EP s3 sync ./public s3://$BUCKET/ --delete
--delete

removes files from the bucket that are no longer present locally — the bucket then becomes an exact copy of the directory.

3. Enabling website mode

aws --endpoint-url $EP s3 website s3://$BUCKET/ \
  --index-document index.html \
  --error-document error.html

Checking the configuration:

aws --endpoint-url $EP s3api get-bucket-website --bucket $BUCKET

4. Making files publicly available

Visitors do not have S3 keys, so the bucket must allow anonymous read access. Save the policy as public-read.json (replace the bucket name):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PublicReadForWebsite",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::moja-strona/*"
    }
  ]
}
aws --endpoint-url $EP s3api put-bucket-policy --bucket $BUCKET --policy file://public-read.jsonaws --endpoint-url $EP s3api put-bucket-policy --bucket $BUCKET --policy file://public-read.json

The policy only allows file downloads — visitors cannot list the contents of the bucket or make any changes. If Public Access Block is enabled on your account, the command will return AccessDenied — in which case you should disable it for this bucket or contact us.

5. Checking that it works

Open https://moja-strona.s3-2website.atman.pl/ in your browser or check it from the terminal:

curl -I https://moja-strona.s3-2website.atman.pl/

An ‘HTTP/2 200’ response means that the page is working.

Content update

To publish a new version of the website, you need to run sync again — only the files that have been changed will be uploaded:

aws --endpoint-url $EP s3 sync ./public s3://$BUCKET/ --delete

File types (Content-Type)

The browser will only display the file correctly if it has the correct Content-Type header. The AWS CLI sets this automatically based on the file extension. If files are uploaded using a different tool and the page downloads as a file rather than being displayed, you must set the type manually:

aws --endpoint-url $EP s3 cp ./public/index.html s3://$BUCKET/index.html --content-type "text/html; charset=utf-8"

Taking the website offline and the most common errors

Disabling the page

Disabling website mode and revoking public access (files remain in the bucket):

aws --endpoint-url $EP s3api delete-bucket-website --bucket $BUCKET
aws --endpoint-url $EP s3api delete-bucket-policy --bucket $BUCKET
aws --endpoint-url $EP s3api delete-bucket-policy --bucket $BUCKET

Complete removal of the bucket, including its contents:

aws --endpoint-url $EP s3 rb s3://$BUCKET --force

The most common mistakes

Symptom

Cause and solution

‘403 Forbidden’ / ‘AccessDenied’ on the page

No public read policy (step 4) or an incorrect bucket name in Resource

404 NoSuchWebsiteConfiguration

Website mode has not been enabled (step 3)

404 NoSuchKey for the home page

The file index.html is missing from the bucket’s root directory

The page opens a list of XML files instead of HTML

The API address (s3-2.atman.pl) was used instead of the website address (<bucket>.s3-2website.atman.pl)

The browser downloads the file instead of displaying it

Incorrect Content-Type — please upload the file again using --content-type

If you encounter any problems, please contact our support team, providing the bucket name, the website address and the output of the command curl -I <address>.