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) |
|
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 |
|
Website mode has not been enabled (step 3) |
|
The file |
The page opens a list of XML files instead of HTML |
The API address ( |
The browser downloads the file instead of displaying it |
Incorrect |
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>.