This Proof of Concept (POC) helps to evaluate the operational portion of the following scenario:
This POC was created to meet the generic system requirements for an architectural component which facilitates the automated creation of static websites.
It should be noted there are many commercial solutions that are viable candidates for this scenario including WordPress .
Website hosting packages, multi-homed or multi-tenant web servers were out of scope for this POC.
At the highest level, the requirements can be represented by the following diagram:
The general requirements include:
There are numerous ways these generic requirements can be met. This particular POC was based on a thought track of utilizing an AWS based approach. Even within AWS, there are numerous ways to meet the generic requirements. This POC evaluates one such approach.
This specific POC was built to evaluate the viability of building an automated solution to deploy an AWS Amplify static website from a template website. When the POC is launched, you will specify a "domain" name which is used to create the github repository, the CloudFormation stack, and the Amplify application. The expectation is to eventually tie the Amplify application to a Route 53 domain name (outside the scope of this POC).
Goals of this POC include the following:
git push origin master on your local machine (pushes locally committed changes to the
github repository), the changes will automatically be picked up by
Amplify and published to the web.I would recommend that you run the POC out of the box, changing as little possible for the first run through. Use the default "template" sample website supplied with the POC. Once you validate that the POC works in your environment, begin experimentation to meet your goals.
WARNING: Review the Amplify cost schedule prior to pushing out an Amplify deployment! It is important to understand what you will be charged for in an Amplify application: AWS Amplify Cost Structure
Major Components:
| Component | Description |
|---|---|
| github | cloud repository where Amplify will automatically pull its source upon each github check-in. By default, the POC create-static-site will create a private github repository (which requires a github paying account). The POC script can be changed to create a public repository. The github repository is created with the same name as the domain name used which launching the POC. The git commits from the local repository to github do not use the tokens in AWS Secrets Manager. It is assumed that you have set up the github repository with SSH access in your local POC development environment, and this is how the POC pushes changes to the github repository. |
| AWS CloudFormation | Builds the Amplify application, Amplify branch, and connects it to github via AWS Secrets Manager. A CloudFormation stack name is created with the same name as the domain used which launching the POC. |
| AWS Amplify | AWS service to host static web-site including support for CDN and certificate management (https://) for the static website. The Amplify application will be created with the same name as the domain name. |
| AWS Secrets Manager | Stores github personal access tokens and github user-name. These tokens allow the POC to create a github repository, connect it to Amplify, and delete the repository when it is no longer needed. I would recommend changing the names of the secrets in AWS Secrets Manager for your deployment, after you run through one test deployment. |
| Development Environment | There is an install script that builds everything you need to run the POC for Ubuntu 18. You can review that script and create your own virtual machine if you prefer another environment. Some of the components installed include: git, jq, curl and aws-shell (optional, though helpful if you are going to experiment). |
To review the source files, please see the POC github Repository
Additional information about files:
It should be noted that you can deploy multiple Amplify applications (static websites) using this POC. The assumption is that all sites go to the same github account for the source code repository. In other words, the following create-static-site(s) will deploy two active web sites, one in us-west-2 and one in us-east-1. The POC will create two repositories in your github account (TestSite01 and TestSite02):
./create-static-site TestSite01 us-west-2
./create-static-site TestSite02 us-east-1
Once you have deployed the static websites, you can permanently delete them by:
./delete-static-site TestSite01 us-west-2
./delete-static-site TestSite02 us-east-1
The table below shows which POC function uses which github tokens. The decision to put the create and delete tokens in AWS Secrets Manager was to help centralize administration of the POC. The create/delete scripts can't operate without access to the appropriate github tokens, which can be managed on a per region basis with AWS Secrets Manager.
Once the Amplify site is deployed, only the read_token is required in AWS Secrets Manager for Amplify to automatically deploy new code to the website as it is pushed to the github repository. The user-name token is used by create-static-site during initial install to test for the github repository before trying to create any of the components (the script will exit if the github repository already exists.)
The POC is intended to be part of a larger workflow where multiple web sites are being managed, though there is no reason it can't be used to set up one static website.
The sys-admin may optionally remove the create_token, delete_token and user_name from AWS Secrets Manager after successful deployment of the website.
It should be noted that since we are manually copying the actual tokens from github to AWS Secrets Manager, the github token names (key names) are irrelevant. Only the AWS Secrets Manager key names (and AWS region) are relevant.
| Secrets Manager Key Name | create-static-site | delete-static-site | Amplify |
|---|---|---|---|
| create_token | |||
| delete_token | |||
| user_name | |||
| read_token |
The github token settings are recorded below. Screen snap-shots are provided of options that must be checked, and not the entire menu of options. Note that you must copy the actual personal access tokens from github into the AWS Secret Manager region where you will run the create/delete scripts, and create your Amplify application. The POC scripts and Amplify use the github tokens stored in AWS Secrets Manager.
I recommend starting with a clean VM - not that this POC does anything out of the ordinary, it is just a best practice I like to use, particularly when working on a POC. You will need the following repository to set up your VM: Set up Development VM
This is a generic script that I use to set up AWS development environments on Ubuntu 18 machines. You can download the zip file, unzip it, move it to a working directory, and run it.
Please review the Readme.MD in this repository, as it contains instructions that must be completed before you proceed with this POC. Again, nothing out of the ordinary, it just saves time if we are working from a know starting point.
You won't need the install script after you run it successfully to completion.
This script sets up all the executables you need to run this POC.
If you can't create a Ubuntu 18 VM, then use the script as a guideline on how to build a (or update an existing) development environment.
cd ~
git clone https://github.com/bill-medved/create-static-amplify-site.git
cd create-static-amplify-site
./create-static-site my_domain my_region
push origin master -u
There is an AWS article that discusses an architectural approach which shifts control to GitHub actions.
I find this an interesting concept that deserves further examination, though I did not have the time to explore this option, which was beyond the scope of the POC timeline:
Deploy CloudFormation stacks with github actions
After you verify that the POC operates in your environment, you may want to adapt it for your use and deploy an Amplify static web site. Think through your directory variables BUILD_ROOT, SOURCE_ROOT and TEMPLATE_ROOT
If you want to deploy your own custom site I would suggest that you set SOURCE_ROOT to a local working directory, and then copy your source code to TEMPLATE_ROOT (BUILD_ROOT/template). Think of the template as a staging area before publishing the application. Remember, the script will create the local git repository on SOURCE_ROOT/DOMAIN. This approach will be the easiest way to leverage the POC.
After you deploy the static website, you should not have to use the POC methods again unless you want to completely remove the Amplify deployment (delete-static-site.sh).
If you do use the delete function, ensure you have updated all directory variables appropriately. Remember delete means all traces of the website are removed, as per POC requirements.
After deploying the website with this POC, your github repository should become your single source of truth--unless this is a component of a larger solution where upstream automated deploys occur to your git repositories.
I highly recommend that you keep a separate copy or your source code until you have verified a clean deployment of your static website into github!