Hosting on Amazon S3 and CloudFront
Amazon S3 is the original object storage service, and CloudFront is Amazon's content delivery network. Together they make a solid home for a static website: S3 stores the files Surreal CMS publishes, and CloudFront serves them on your domain over HTTPS. This page walks you through the whole setup in the AWS console, with CloudFront's caching turned off so your edits go live the moment you publish.
This is the longest of our hosting guides
AWS gives you a lot of control, and the price is a lot of steps. None of them are difficult, but expect to spend a little while in the console. If you're not already invested in AWS, Cloudflare R2 gets you to the same place with less work.
Before you start
All of the following need to be true before you begin:
- You have an AWS account and can sign in to the console with permission to manage S3, IAM, and CloudFront.
-
You can add DNS records for your website's domain. Any DNS provider works, but if you want to use an
apex domain, like
example.comrather thanwww.example.com, your provider needs to support ALIAS records or something equivalent. Amazon Route 53 does. - You're using one bucket per website, and you're not storing drafts, backups, or anything private in it.
How the pieces fit together
| S3 bucket | Stores the files Surreal CMS publishes. It stays private. Visitors never talk to it directly. |
|---|---|
| IAM user | Gives Surreal CMS an access key that can read and write files in that one bucket |
| CloudFront distribution |
Serves the bucket's files to the public over HTTPS, e.g.
https://www.example.com/index.html
|
| CachingDisabled policy | Tells CloudFront to fetch every request from S3 so published edits appear immediately |
| CloudFront function |
Makes / load index.html and /blog/ load
blog/index.html (required)
|
| Custom error response | Shows your 404.html when a file is missing (optional) |
| Certificate and DNS records | Put the distribution on your own domain |
This is the setup AWS recommends: a private bucket that only CloudFront can read, using a feature called origin access control. You may have seen older tutorials that turn on S3's "static website hosting" and make the bucket public. That still works, but it requires disabling S3's Block Public Access protections, and traffic between CloudFront and S3 can't use HTTPS.
1. Create the bucket
Sign in to the AWS console and open S3. Choose a Region from the navigation bar at the top. Pick the one closest to most of your visitors.
- In the left navigation pane, choose General purpose buckets, then choose Create bucket.
-
Enter a Bucket name. Names are 3–63 characters, begin and end with a letter or number,
and contain only lowercase letters, numbers, and hyphens, e.g.
my-website-files. Periods are allowed too, but AWS recommends avoiding them. The name has to be unique across all AWS accounts, not just your own. If you're offered a choice of bucket namespace, keep the global one. The account regional namespace adds a suffix to the name you type, and you'd need to use the full name, suffix included, everywhere this guide asks for the bucket name. - Leave Object Ownership set to Bucket owner enforced, which is the default. This means ACLs are disabled.
- Leave all four Block Public Access settings enabled, which is also the default.
- Leave the rest of the settings alone and choose Create bucket.
Name and Region are permanent
You can't change a bucket's name or Region after you create it. Make a note of both. You'll
need them when you connect Surreal CMS. The Region you need is the code, such as
us-east-1, not the display name.
Now open the bucket and upload your website's files using the Upload button. Keep the
same folder structure your pages expect, with index.html at the top level. If you plan to use a
custom 404 page, add 404.html too. This is also a good time to create the folder Surreal CMS
will store uploads in. Choose Create folder and name it uploads. To upload
from the command line instead, or to have an agent do it, see
Hosting an Agent-Built Website on Amazon S3.
2. Create an IAM user and access key
Surreal CMS needs an access key to read and write files in your bucket. Rather than using your own credentials, create a user that can only touch this one bucket.
- Open IAM in the AWS console. In the navigation pane, choose Users, then choose Create user.
-
Enter a User name, e.g.
surreal-cms, and choose Next. Don't give the user console access. - Skip the permissions page for now by choosing Next, then choose Create user.
- Open the new user and choose the Permissions tab. Choose Add permissions, then Create inline policy.
-
In the Policy editor, choose JSON and replace the contents with the
policy below. Change
my-website-filesto your bucket's name in both places.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws:s3:::my-website-files"
},
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject",
"s3:AbortMultipartUpload"
],
"Resource": "arn:aws:s3:::my-website-files/*"
}
]
}
-
Choose Next, give the policy a name, e.g.
surreal-cms-bucket-access, and create it. - Choose the Security credentials tab. In the Access keys section, choose Create access key.
- AWS shows a page of best practices and alternatives. Choose Other as your use case, then choose Next and Create access key.
-
Copy the Access key and Secret access key, or download the
.csvfile. This is the only time AWS will show you the secret.
3. Connect your website to Surreal CMS
Log in to Surreal CMS, then select New Site on the Sites page. Choose Amazon S3 for the protocol and fill out the form.
| Name | The name you want to use for your website. (Only used in the CMS.) |
|---|---|
| URL |
The domain your visitors will use, e.g. https://www.example.com/Important! Use your own domain here, not an amazonaws.com or
cloudfront.net address. You'll connect the domain in steps 7 and 8.
|
| Protocol | Amazon S3 |
| Region | Your bucket's Region code, e.g. us-east-1. |
| Bucket | The exact name of the bucket you created. |
| Access Key | The access key from your IAM user. |
| Secret Access Key | The secret access key from your IAM user. |
| Access Control List (ACL) | Leave this off. Your bucket has ACLs disabled, and S3 rejects uploads that include an ACL when that's the case. This option only exists for older buckets that serve files publicly using ACLs. |
| Home Folder | The folder that contains your homepage. Use the Browse button to navigate to it. For a bucket that holds a single website, this is the root of the bucket, so you can leave it blank. |
| Upload Folder |
The folder that uploaded files will be stored in. It has to be inside your home folder. Users can
upload, rename, move, and delete anything inside this folder, but nothing outside of it, so don't
select one that contains webpages or other important files. Create a folder called
uploads for this purpose. See
best practices for why.
|
Select Test Connection to make sure everything works. If all goes well, you'll see Connection successful!
If the connection fails, double check the Region and bucket name, and make sure the bucket name in your IAM policy matches in both places.
4. Create the CloudFront distribution
Open CloudFront in the AWS console.
- Choose Distributions, then Create distribution.
- If you're asked to choose a pricing plan, choose pay-as-you-go. See the note below.
- Enter a Distribution name, choose Single website or app, and choose Next.
- Skip the optional domain setup unless your domain is managed by Route 53. You'll add your domain in step 7.
- For Origin type, choose Amazon S3. Choose Browse S3 and select your bucket.
- Choose Use recommended origin settings. This sets up origin access control so CloudFront can read your private bucket.
- On the Enable security protections page, choose whether you want AWS WAF. It's optional with pay-as-you-go pricing and it costs extra.
- Review your settings and choose Create distribution.
CloudFront attempts to update your bucket's policy so the distribution can read from it. To confirm,
open your bucket in the S3 console, choose the Permissions tab, and look at the
Bucket policy. You should see a statement that allows
cloudfront.amazonaws.com to perform s3:GetObject. If it's missing, copy the
policy from
AWS's origin access control documentation
and fill in your bucket name, account ID, and distribution ID.
Your distribution has a domain name that looks like d111111abcdef8.cloudfront.net. You'll
use it to test your website after the next step.
Why pay-as-you-go?
CloudFront also offers flat-rate pricing plans, including a free one. Those plans limit some features: custom caching rules are only included with the Business and Premium plans, and every plan requires AWS WAF. Pay-as-you-go has no feature limitations and includes an always-free allowance of 1 TB of data transfer and 10 million requests per month, which is plenty for most websites.
5. Turn off caching
New distributions use a cache policy called CachingOptimized, which keeps files at CloudFront's edge for up to 24 hours by default. For a website you edit with a CMS, you want CloudFront to check S3 every time.
- Open your distribution and choose the Behaviors tab.
- Select the default behavior and choose Edit.
- In the Cache key and origin requests section, make sure Cache policy and origin request policy is chosen. For Cache policy, choose CachingDisabled.
- While you're here, confirm Viewer protocol policy is set to Redirect HTTP to HTTPS.
- Choose Save changes.
Once the distribution finishes deploying, open
https://d111111abcdef8.cloudfront.net/index.html with your own distribution's domain name
to confirm your homepage loads.
6. Make your homepage load at /
Right now /index.html works but / doesn't. CloudFront has a
default root object setting, but it only applies to the very top of your website. It won't
make /blog/ load blog/index.html. A CloudFront function handles both.
- In the CloudFront console, choose Functions, then Create function.
-
Enter a name, e.g.
add-index-html, and make sure the JavaScript runtime is version 2.0 (cloudfront-js-2.0), not 1.0. Then continue to create the function. - On the Build tab, replace the function code with the following and choose Save changes. This is AWS's own sample for this purpose.
async function handler(event) {
var request = event.request;
var uri = request.uri;
// Check whether the URI is missing a file name.
if (uri.endsWith('/')) {
request.uri += 'index.html';
}
// Check whether the URI is missing a file extension.
else if (!uri.includes('.')) {
request.uri += '/index.html';
}
return request;
}
- Choose the Publish tab, then Publish function.
- Choose Add association. Select your distribution, choose Viewer Request for the event type, select the default cache behavior, and choose Add association.
Once the distribution finishes deploying, / serves index.html,
/blog/ serves blog/index.html, and so does /blog. Link to folders
with the trailing slash anyway. Without it, browsers resolve relative links such as
href="style.css" against the wrong folder.
Optional: Clean URLs
The function above assumes that a path without a file extension is a folder, so
/about looks for about/index.html. If your pages are saved as
about.html and you want /about to serve them, change the second
request.uri line to this, then save and publish the function again:
request.uri += '.html';
Pick one convention or the other. A single function can't tell whether /about is meant to
be a page or a folder. Also note that the function treats any path containing a dot as a file, so a path
such as /v1.2/notes is passed through unchanged.
Optional: A custom 404 page
When a file doesn't exist, visitors see an XML Access Denied error. That's because CloudFront is only allowed to get objects, not list the bucket, and in that situation S3 answers with a 403 instead of a 404. A custom error response turns that into your own page.
- Publish
404.htmlto your bucket and confirm it loads at/404.html. - Open your distribution, choose the Error pages tab, and choose Create custom error response.
- For HTTP error code, choose 403: Forbidden.
-
Choose to customize the error response. Set Response page path to
/404.htmland HTTP response code to 404: Not Found so search engines still see a not-found response. - Create the error response.
You can leave Error caching minimum TTL alone. With the CachingDisabled policy, CloudFront doesn't cache error responses or custom error pages, so a newly published page is available right away.
7. Request a certificate and add your domain
Your website works at its cloudfront.net address now. This step puts it on your own domain.
- Open your distribution. On the General tab, under Alternate domain names, choose Add a domain.
- Enter your hostname, e.g.
www.example.com, and choose Next. -
For TLS certificate, let CloudFront create a certificate for you. CloudFront certificates
always live in the US East (N. Virginia) Region,
us-east-1, no matter where your bucket is. If you'd rather request one yourself in AWS Certificate Manager, make sure you switch to that Region first. - CloudFront shows one or more CNAME records that prove you own the domain. Add them at your DNS provider exactly as shown, then choose Validate certificate. You only need to add these records once. Leave them in place so the certificate can renew automatically.
- Choose Next, then Add domains.
8. Point your domain at CloudFront
The last step is a DNS record that sends visitors to your distribution.
| Subdomain, any DNS provider |
Create a CNAME record for www that points to your distribution's
domain name, e.g. d111111abcdef8.cloudfront.net.
|
|---|---|
| Apex domain |
The DNS protocol doesn't allow a CNAME record at the top of a domain, so
example.com needs an ALIAS record instead. Route 53 supports these. If your DNS provider
doesn't offer an equivalent, use www.example.com for your website.
|
| Route 53 | Choose Route domains to CloudFront in the CloudFront console and it will update your DNS records for you. To do it by hand, create an A record with Alias turned on, routed to Alias to CloudFront distribution, and a matching AAAA record if your distribution has IPv6 enabled. |
Once DNS updates, your website is live at https://www.example.com/.
Fonts and scripts in the editor
Surreal CMS loads your page from its own origin to edit it, so web fonts and JavaScript modules are
cross-origin requests in the editor, and browsers block them unless the response allows it. Without that
permission, the editor shows your site in a fallback font and type="module" scripts
don't run. Visitors aren't affected.
CloudFront can add the permission. Open your distribution's Behaviors tab, edit the
default behavior, set Response headers policy to the managed policy
SimpleCORS, and save. It adds Access-Control-Allow-Origin: * to responses to
cross-origin requests. If S3 already sends that header for a file, CloudFront keeps S3's value.
Testing your setup
Once everything's in place, check these URLs. Replace the hostname with your own.
/index.html |
Your homepage. This works even without the function. |
|---|---|
/ |
Your homepage, once the function is published and associated. |
/about.html |
Your about page. |
/about |
about/index.html, or about.html if you made the clean URL change. |
/styles.css |
Stylesheets, images, and other static files. |
/this-does-not-exist |
An XML error, or your 404.html if you added a custom error response. |
http:// instead of https:// |
Redirects to https://. |
Finally, edit a page in Surreal CMS, publish it, and reload it on your domain. The change should be there right away.
How publishing stays instant
Two things work together here. S3 is strongly consistent, which means that as soon as Surreal CMS finishes writing a file, the next read gets the new version. And with the CachingDisabled policy, CloudFront asks S3 for the file on every request instead of keeping its own copy. There's nothing to invalidate after you publish.
As a second line of defense, Surreal CMS sends a Cache-Control: no-cache header with every file
it uploads. If you ever switch back to the CachingOptimized policy, CloudFront will hold those files for no
more than a second. Files that got into your bucket some other way don't have that header, so
CloudFront would cache them for up to 24 hours and you'd need to create an invalidation to clear them.
Performance and cost
With caching disabled, every request travels to your bucket's Region. Visitors still connect to a nearby CloudFront location and ride Amazon's network from there, which AWS says improves performance even for content that isn't cached. But a visitor far from your bucket will wait longer than they would for a cached copy. That's the trade you make for instant publishing.
There's one more cost: CloudFront doesn't compress files when caching is turned off, so your HTML,
CSS, and JavaScript are sent at full size. If that matters more to you than a strict guarantee, the
CachingOptimized policy is a reasonable middle ground. It keeps compression, and because of the
no-cache header described above, files uploaded by Surreal CMS are still held for no more than
a second. The catch is that files added any other way are cached for up to 24 hours.
With pay-as-you-go pricing, CloudFront's always-free allowance covers 1 TB of data transfer out, 10 million requests, and 2 million function invocations each month. Data transferred from S3 to CloudFront is free. You do pay S3 for storage and for requests, and with caching disabled every page view results in requests to S3. For a typical brochure website this comes to very little, but check the S3 and CloudFront pricing pages for current rates.
A few other things worth knowing: the function runs on every request, so it counts against the function allowance; there's no atomic deploy or preview URL since publishing overwrites files in place; and the custom error response turns every 403 from S3 into your 404 page, including ones caused by a broken bucket policy. If your whole website suddenly shows the 404 page, check the bucket policy first.
Checklist
- One private bucket per website, with ACLs disabled and Block Public Access left on
- An IAM user whose inline policy is limited to that bucket, and an access key for it
- Surreal CMS connected with the ACL option turned off
- A pay-as-you-go CloudFront distribution with your bucket as its origin, using the recommended origin settings
- A bucket policy that lets
cloudfront.amazonaws.comget objects - The default behavior set to the CachingDisabled cache policy
- A published CloudFront function associated with the Viewer Request event
- The SimpleCORS response headers policy on the default behavior
- Optionally, a custom error response that maps 403 to
/404.htmlwith a 404 status - A validated certificate, your domain added to the distribution, and a DNS record pointing to it
- No private files in the bucket
If you run into trouble getting connected, feel free to contact us for help!