Recently I started working on this very same website, and I wanted to avoid using something like Wordpress, and don’t get me wrong, Wordpress is great, but I wanted to use AWS for hosting, and the cost wasn’t just worth it. So I decided to build a static website and use the power of S3 and Cloudfront to host it.
Here is were Hugo came into the picture. It was a great way to build my website and blog as static content. I was super happy with it and I had it running locally in no time, but then it was time to deploy it to AWS and for the most part, it just worked, except for a minor detail, pretty URLs were not working at all.
In this post, I’ll cover how to configure and deploy your Hugo website (or any other static website) using AWS S3 and Cloudfront.
Build your website
I won’t go here into details and there are a lot of tutorials on how to do this with Hugo or any other tool. But if you need a hint, I used this tutorial from the Hugo official documentation that is a great start.
Configuring the platform
In this section, we will cover how to set up your S3 bucket, create your Cloudfront distribution, and deploy your static website.
Create the S3 bucket
- Sign in to the AWS Management Console and open the Amazon S3 console at https://console.aws.amazon.com/s3/.
- Choose Create Bucket and complete the form as follows:
- Enter the Bucket Name
Note that the name must be DNS-complaint and that is unique across all of Amazon S3.
- Select the region
Choose a Region close to you to minimize latency and costs and address regulatory requirements.
- Select Block all public access
This option is currently the default.
- Click Create Bucket
Create the Cloudfront Distribution
- Open the Amazon Cloudfront console at https://console.aws.amazon.com/cloudfront/home
- Choose Create Distribution and complete the wizard as follows:
- Choose Web as the delivery method for your content.
- Complete the form and in addition to the distribution settings that you need for your use case, enter the following:
- For Origin Domain Name, select the bucket that you created.
- For Restrict Bucket Access, select Yes.
- For Origin Access Identity, select Create a New Identity.
- For Comment, you can choose to keep the default value. Or, you can enter a custom label for the OAI.
- For Grant Read Permissions on Bucket, select Yes, Update Bucket Policy.
- If you don’t want to use SSL (HTTPS) for your website, proceed to the next step. To use SSL for your website, for SSL Certificate, you can select the Default CloudFront Certificate or a Custom SSL Certificate. Or, you can choose Request or Import a Certificate with ACM to request a new certificate.
- Choose Create Distribution
- Update the DNS records for your domain to point your website’s CNAME to your CloudFront distribution’s domain name. You can find your distribution’s domain name in the CloudFront console in a format that’s similar to d1234abcd.cloudfront.net.
Wait for your DNS changes to propagate and for the previous DNS entries to expire.
Deployment from Hugo to AWS is very straight forward and well documented in the official docs.
For deploying I’m using a bash script which simplifies my workflow, here is how it works
Done! it’s deployed. Here is the code to the script
echo "Deleting old files"
rm -rf public
hugo deploy --maxDeletes -1 --invalidateCDN
echo "Deployment Completed!"
Don’t forget to give the script execution rights.
After some testing you may realize that some links don’t work, they give an “Access Denied” Error. So what is going on? Well… When we generate a website with Hugo (or many of the other static CMSs out there) you will find that each page gets generated as follows:
/about/index.html, but that's probably not how you set up your links in the app, you probably had something like
Why is Cloudfront not resolving the directories and using the Default root page? The problem lies within hosting a site on S3 through CloudFront. CloudFront uses the S3 API to find files, and the API is a bucket with file references, imitating a folder structure. Enabling website hosting for an S3 bucket will allow you to redirect traffic to the S3 HTTP endpoint which simulates a web server, but when using CloudFront in front of it you are not allowed to do that anymore. It effectively disables the Apache- or Nginx-like behavior where you can assign a directory index. CloudFront does not know you are referring to a folder.
The Solution: Lambda@Edge
After looking around the internet for a while I found a solution using Lambda@Edge to generate redirects which we can control to append the
/index.html to the user entered URLs.
What is Lambda?
For those that don’t know yet, AWS Lambda is a service that lets you run pieces of code on demand, without the need to manually launch a server. In their own words:
AWS Lambda lets you run code without provisioning or managing servers. You pay only for the compute time you consume.
I worked in the past quiet a bit wit Lambda, however I never used this functionality with Cloudfront, nor I knew it was even possible.
Now it’s possible to write your function and do all the configurations manually, and that’s what I did, however after looking some more I found an easier way using standard-redirects-for-cloudfront repository.
- Go to Serverless Application Repository.
- Press the Deploy button.
- It opens a new modal with the description of the app, press Deploy again to create all the resources.
- After it has been created, locate the button View CloudFormation Stack or go directly to the Cloudformation Console.
- In the Resources tab, locate the
AWS::IAM::Roleand open the Physical ID, it will open up the IAM console.
- Go to Trust Relationship tab and choose Edit the trust relationship to allow CloudFront to execute this function as a Lambda@Edge function., set the policy to:
- Go back to the Cloudformation’s Stack Detail page and in the Output tab, locate the key
StandardRedirectsForCloudFrontVersionOutputand note down its Value (it will look something like:
arn:aws:lambda:us-east-1:XXXXXXXXXXX:function:aws-serverless-repository-StandardRedirectsForClou-XXXXXXXXXXXX:2). We will use it in the next steps as this is the ARN (Amazon Resource Name) for the Lambda function that we will use in Cloudfront.
- Go back to the CloudFront console, select your distribution
- Go to the Behaviour tab and edit the default Behavior.
- Now we use the Lambda function, in Lambda Function Association select Event Type/Origin Request and enter the Lambda function’s StandardRedirectsForCloudFrontVersionOutput ARN value from the previous step.
Wait for a few minutes for Lambda@Edge to do its thing
Now it just works!
Congratulations, your static website is now working properly!
Originally published at https://livecodestream.dev.