How to setup Continuous Deployment to AWS S3 using CircleCI in just 30 minutes
Continuous Deployment might seem complicated at first, but don’t be intimidated. In this tutorial, I’ll show you how to implement Continuous Deployment to AWS S3 for a static website using CircleCI in less than 30 minutes.
You’ll need both an AWS account and a CircleCI account. If you don’t have these yet, start by opening a free account for AWS here and a free CircleCI account here . Both AWS and CircleCI have a free tier that’s more than enough for what you will need for this tutorial.
Getting the code
First you will start by forking and cloning the following project repo on Github: S3ContinuousDeploy or if you prefer you can try this tutorial with one of your own repos as long as it’s a static site.
Next you will add the project to your CircleCI account.
Next select the S3ContinuousDeploy repo you just cloned and click build project.
At this point the build will run, but you will be getting an error message warning you that the settings for your project couldn’t be detected. Which is normal since we don’t have a circle.yml configuration file in place, which is what you will be doing next.
Looking at the docs at CircleCI you can get an idea of what the circle.yml should look like. Unfortunately the circle.yml file example provided will not work as is and will need some tweaking, so let’s do that.
Below is the modified circle.yml file you will be using:
Basically CircleCI creates the build within a Docker container, and the override under dependencies property (line 3) that I added instructs CircleCI to install the AWS command line interface (awscli) that will be used in this case to help manage and facilitate deployment to AWS S3.
So make sure you add the file and commit it to your repo. Finally make sure you push this and other commits you might have made before you proceed to the next step.
As per CircleCI documentation the command for deploying is:
The path-to-file was a bit tricky to figure out but by looking at the error logs I was able to finally get it right: home\ubuntu\projectName. So just replace projectName with the name of your project, in my case that will be S3ContinuousDeploy.
The S3://bucket-URL on the other hand is not correct and should be S3://bucket-Name. Right now we don’t have a bucket name, so let’s get ourselves a bucket.
Creating the S3 bucket
In this step we will be heading to the AWS Console to create the S3 bucket for this project:
Enter the bucket name you would like to use for this project as well as the region. (The best practice is to use the region nearest to your site’s audience.)
You will skip the other steps for now so press “Next” and then press “Create bucket” on the review screen.
At this point if you go back to CircleCI and try to run the build again CircleCI will return a fatal error: Unable to locate credentials. So why don’t we fix that next.
We need to first get the credentials from AWS and then provide them to CircleCI in order to allow the AWS cli to access and manage the S3 bucket. Best practice for this is to create a new Identity and Access Management (IAM) user specifically for CircleCI.
On the AWS console go to Security, Identity & Compliance and press IAM and then Add user.
In the Add User window type in CircleCI for User name, I already have an IAM user named CircleCI setup, So for the purposes of this tutorial and to illustrate these steps I will be using CircleCI2. Make sure you check Programmatic access for Access type.
For permissions choose Attach existing policies directly, and under Policy name check ‘AdministratorAccess’ and then click Create policy. This will provide your IAM user full access to your AWS S3 bucket.
After creating the IAM user, make sure you keep both the Access key ID and the Secret access key, as we will need them in the next step.
Now back to CircleCI, click on the settings button next to your project name to reveal the project settings menu then click on AWS Permissions. This is where you will paste the ID and Key from the previous step and then click “Save AWS keys.”
Now our CircleCI Container has both the AWS Command Line Interface tool and the credentials to access the AWS S3 bucket. The following steps will show you how to reveal your static site to the world.
In the AWS console go to Storage and then click on S3 and then click on the bucket we created earlier in this tutorial.
You will notice that the code from the repo has already been successfully deployed.
Now before you can access this static site you need to configure your S3 bucket for website hosting.
On the same screen click on Properties and then on Static website hosting.
In the following screen select Use this bucket to host a website and make sure you type in index.html for Index document.
By the way, the HTTP address provided above is your access endpoint. But if you try it in the browser unfortunately it won’t work and you will get an access denied error message. But that’s normal you still have one step to do: Set up your bucket policy.
This Bucket policy will allow access to the AWS S3 bucket to anyone via a browser.
You can read up here on bucket policies and examples if you want to learn more.
Now you can copy the code snippet above and paste it in your Bucket policy Editor and Voila!
If you see the screen above, then Congratulations! You have successfully set up Continuous Deployment to an AWS S3 bucket using CircleCI.
Now every time you push changes to your Github repo, CircleCI will automatically deploy the changes to your AWS S3 bucket.
You might have noticed that even though the deployment was successful CircleCI shows you a red NO TESTS warning.
This is normal because in a Test Driven Development (TDD) environment you would write tests first, and then before going to production your code needs to pass all the tests. An example with tests is beyond the scope of this tutorial, but suffice it to say that had we written tests, CircleCI would only have deployed if all our tests passed.
Using your own domain name to access this static site is also beyond the scope of this tutorial, but feel free to look here for instructions on how to configure Amazon Route 53 to route Internet traffic to your new site.
I am hoping to do a tutorial involving a Continuous Integration/Deployment example with a full battery of tests sometimes in the future. Meanwhile, if you have a moment, answer a short survey about this tutorial here, like it on LinkedIn or post a comment in the comments section.
Thanks for reading!