Automated CLI for static web application hosting on AWS using S3 buckets.
This automated script simplifies setting up an AWS site. Add S3 buckets, register DNS, and create an SSL certificate in minutes with no DevOps knowledge.
Capsule uses the following AWS technologies:
- Amazon S3
- Amazon CloudFormation
- Amazon Certificate Manager
- Amazon Route53
- Amazon CloudFront
- Amazon CloudBuild
If you are exploring how to deploy a single page web application (SPA) this may be a good option for you.
If you need a more comprehensive set of development tools and processses that encompass a wider variety of AWS services, for example, AWS Lambda, you might consider using the AWS Amplify Console instead as part of a more comprehensive application development pipeline that uses AWS and DevOps concepts.
Install capsule as a global CLI from NPM.
npm install -g capsuleYou can now use capsule from your command line.
In order to use Capsule you will need the following:
- An AWS account. You can sign up here: https://aws.amazon.com/
- A registered domain name. This can be obtained through AWS or via a third party such as GoDaddy.
- For continuous integration, a source code repository such as GitHub where your static website is located
- A static website (HTML, JS, CSS) that does not require server side code like PHP, Python or Java.
In order to use the Capsule command line interface you will need a number of security credentials. These credentials are used by the script to interact with your AWS account.
Currently only a few regions can handle Certificate Manager in combination with CloudFront. You should therefore when creating the configuration described in the next section, ensure you chose a region that supports these features.
Amazon provides a fature list at the following site:
https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/
A safe bet is to use us-east-1 as this is the region that Capsule has been tested in.
First we are going to create a single file config.json
We a need directory to store this file, so create a new directory .aws under the root of your user
Mac/Linux
mkdir ~/.aws
Windows
%UserProfile%\.aws
Next create the config.json file in the .aws directory, containing these keys:
{
"accessKeyId": <YOUR_ACCESS_KEY_ID>,
"secretAccessKey": <YOUR_SECRET_ACCESS_KEY>,
"region": "us-east-1"
}After creating these files, log into your AWS account. We now need to create an Access Key. This can be done as follows:
- Open your AWS Console
- Click on your username in the top right
- Select
My Security Credentials - Fromt he screen that loads, click on
Usersin the sidebar - Next click on your username in the table
- When this loads, click on the
Security Credentialstab - We can now create an Access Key by clking
Create Access Key - Finally click
Show User Security Credentialsand copy the ID and value.
These details can only be displayed once, so if forget or lose them, you will need to generate a new key. If you wish you can download the CSV file from this screen as a backup.
Re-open the config file e.g. vim ~/.aws/config.json
Now replace the accessKeyId value (<YOUR_ACCESS_KEY_ID>) with the value you copied from the AWS console.
Next replace the secretAccessKey value (YOUR_SECRET_ACCESS_KEY) wuth the key you copied from the console.
Make sure you wrap the value you paste in with " and ".
You can change the region if you wish as well, but please check the region supports all the features required by Capsule.
Save the file. You are now ready to use Capsule to build out your static site.
First we are going to create two files. These are the config and credentials file.
Create a new directory .aws under the root of your user
Mac/Linux
mkdir ~/.aws
Windows
%UserProfile%\.aws
Next create a credentials file in the .aws directory, containing these keys:
[default]
aws_access_key_id=
aws_secret_access_key=After this, create a config file in the .aws directory and include the following:
[default]
region=
output=After creating these files, log into your AWS account. We now need to create an Access Key. This can be done as follows:
- Open your AWS Console
- Click on your username in the top right
- Select
My Security Credentials - Fromt he screen that loads, click on
Usersin the sidebar - Next click on your username in the table
- When this loads, click on the
Security Credentialstab - We can now create an Access Key by clking
Create Access Key - Finally click
Show User Security Credentialsand copy the ID and value.
These details can only be displayed once, so if forget or lose them, you will need to generate a new key. If you wish you can download the CSV file from this screen as a backup.
Re-open the credentials file e.g. vim ~/.aws/credentials
Paste the ID into the key id value:
aws_access_key_id=<the id you copied here>Following this, paste the secret value into the secret key value:
aws_secret_access_key=<the key value you copied here>Our final step is the edit the config file and set a region and output type.
You can chose whichever region makes sense to you, we are going to use us-east-1, and set the output to json.
[default]
region=us-east-1
output=jsonSave the file.
Your credentials and configuration are now setup to use Capsule.
In order to create the config.json file containing your project configuration
run the command capsule.js init
Answer the questions presented to you on the screen.
If you wish to run multiple bash commands inside of the build or post_build
CodeBuild actions, then you will need to pass these as a single parameter.
Use the following chart as a guide for bash commands:
A ; B # Run A and then B, regardless of success of A
A && B # Run B if and only if A succeeded
A || B # Run B if and only if A failed
In the nodejs world for example this could translate to the following:
npm build dev ; npm test
During the setup of your site you will need to define a project name. This will be used to name the S3 bucket in AWS. Therefore your project name must confirm to the S3 bucket naming standards.
You can find these here:
https://docs.aws.amazon.com/AmazonS3/latest/dev/BucketRestrictions.html
Once the capsule.json file is generated, you are now ready to deploy your project to
your AWS account.
To do this, simply type:
capsule.js deploy
If you wish to learn more about the templates that are implemented by the deploy command, please refer to the templates read me file.
In order to authorize your certificate you will need to log into the AWS console.
Depending on whether you are using DNS or Email authorization you will need to follow the relevant steps below.
As part of the process of creating your static site, you will need to point an existing domain or subdomain to your S3 bucket.
When executing the web command from the cli the process will halt once it reaches the certificate manager portion.
At this point you should log into your AWS console and select the Certificate Manager service. On this screen the domain
you passed to the cli should be visible e.g. example.com.
Open up the drop-down arrow for the domain and follow the insturctions provived bu Amazon to validate control of the domain. Note that Amazon will send an email to your account at:
Where example.com is the domain you passed to the cli tool.
Once the CloudFormation templates are kicked off the CloudFront stack process, you can expect to wait around ~20 mins for this process to complete.
You can check on progress under the CloudFront services home page:
https://console.aws.amazon.com/cloudfront/home?region=us-east-1
Capsule allows for Continuous Integration (CI) of your changes from a source code repository. As present the CI is currently using codebuild only.
The cloudformation template codebuild.cf allows you to quickly setup a basic CI infrastructure for any repository.
The following section lists any specific requirements for source control products and services.
The AWS codebuild service must be already authenticated with Github using OAuth before creating the stack. You can read more on OAuth integration steps on GitHubs website here:
https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/
Make sure that the user you have setup in GitHub, to be used by CodeBuild has admin permissions on the repository.
If it does not, you may see errors such as:
Repository not found or permission denied. (Service: AWSCodeBuild; Status Code: 400; Error Code: OAuthProviderException; Request ID: <an id value>)
This is especially important if you wish to manage webhooks e.g.
Triggers:
Webhook: yes
In this case, the user will need Admin permissions.
You will need to create a webhook in GitHub.
Capsule comes with a number of advanced options. These allow:
- A more granular deployment process
- Overridding default settings in the capsule.json with command line values
To read me please check out the documentation here.
To learn more about the CloudFormation templates that make up a portion of the capsule project please refer to the template documentation here.
To learn about our contributor guidelines, please check out the documentation here
Modus Create is a digital product consultancy. We use a distributed team of the best talent in the world to offer a full suite of digital product design-build services; ranging from consumer facing apps, to digital migration, to agile development training, and business transformation.
This project is part of Modus Labs.
This project is MIT licensed.