Repository files navigation

Host your static website on AWS via S3, with global CDN via CloudFront, using SSL certificates provided by ACM using your own domain name!

All set up via oneServerless command and minimum manual configuration!

• A S3 bucket containing your static website
• A CloudFront distribution for global hosting via CDN
• A HostedZone on Route53 with A records for your domain name
• A Lambda function for automatic SSL certificate generation via ACM for your domain name (run once upon deployment)

This guide assumes that you have a pre-existing domain which you want to use for hosting your static website. Furthermore, you need to have access to the domain's DNS configuration.

Also, you need to have an install ofServerless on your machine.

To use this blueprint with your own static websites, you can follow the steps below to get started.

There are basically two ways to get started, either useServerless to generate a basic project structure, or use the "traditional" fork and clone mechanisms.

The following command will create a local project structure you can use to deploy your static website in themystaticwebsite folder relative to your current working directory:

$ sls create --template-url https://github.com/tobilg/serverless-aws-static-websites --path mystaticwebsiteServerless: Generating boilerplate...Serverless: Downloading and installing"serverless-aws-static-websites"...Serverless: Successfully installed"serverless-aws-static-websites"

Hint
When using this method, Serverless is replacing theservice.name in theserverless.yml file automatically withmystaticwebiste. If you want to use a different stack name, you have to replace it manually. You also need to take care of that the stack name is using only allowed characters. When using the "Fork and clone" method below, the stack name is automatically derived from the domain name and sanitized regarding the allowed characters.

Once you forked the repo on GitHub, you can clone it locally via

$ git clone git@github.com:youraccount/yourrepo.git

whereyouraccount/yourrepo needs to be replaced with the actual repository name of your forked repo.

To install the dependencies, do a

$ npm i

After that, the project is usable.

You can now create your static website in thesrc folder of your cloned repo.

You can deploy your static website with the following command:

$ sls deploy --domain yourdomain.yourtld

whereyourdomain.yourtld needs to be replaced with your actual domain name. You can also specify a AWS region via the--region flag, otherwiseus-east-1 will be used.

On the first deploy, it is necessary to update the DNS setting for the domain manually, otherwise the hosted zone will not be able to be established.

Therefore, once you triggered thesls deploy command, you need to log into the AWS console, go to theHosted Zones menu and select the corresponding domain name you used for the deployment.

The nameservers you have to configure your domain DNS to can be found under theNS record and will look similar to this:

ns-1807.awsdns-33.co.uk.ns-977.awsdns-58.net.ns-1351.awsdns-40.org.ns-32.awsdns-04.com.

You should then update your DNS settings for your domain with those values,otherwise the stack creation process will fail.

This is a bit misfortunate, but to the best of knowledge there's currently no other way possible if you use AWS external (non-Route53) domains. During my tests withnamecheap.com domains the DNS records were always updated fast enough, so that the stack creation didn't fail.

As a new CloudFront distribution is created (which is pretty slow), it can takeup to 45min for the initial deploy to finish. This is normal and expected behavior.

If the deployment finished successfully, you will be able to access your domain viahttps://www.yourdomain.yourtld andhttps://yourdomain.yourtld.

This setup should give you some goodPageSpeed Insights results.

For every update of your website, you can trigger a deploy as stated above. This will effectively just do s S3 sync of thesrc folder.

To do a manual sync, your can also usesls s3sync. There's also the possibility to customize the caching behavior for individual files or file types via theserverless.yml, see thes3sync plugin's documentation.

AsCloudFront caches the contents of the website, aServerless plugin is used to invalidate files. Thismay incur costs, see thedocs for more info.

You can runsls cloudfrontInvalidate to do a standalone invalidation of the defined files in theserverless.yml.

If you want to remove the created stack, you will have to delete all records of the Hosted Zone of the respective domain except theSOA andNS records, otherwise the stack deletion via

$ sls remove --domain yourdomain.yourtld

will fail.