cloudmason v1.0.10

Set up an AWS organization from scratch and deploy a static site or AMI-based EC2 application in just 4 commands.

The tool will handle everything from obtaining ACM certificates to building AMIs and deploying cloudformation stacks.

Can be used as a command line tool, or in a CI/CD pipeline.

Contents

• Quick Start
• Important Notes
• Commands

Installation

Be sure to use the -g flag to install globally.

npm install -g cloudmason

Quick Start

Get an Ec2 nodejs app up and running in 4 commands.

1. Prereqs
   1. Open an AWS account
   2. Download and set up the AWS CLI (or just set your AWS credentials with enviroment variables)
   3. Ensure you have a domain to deploy apps to
   4. Make sure you have nodejs version 18+ installed
   5. Install the cloudmason CLI
      • npm install -g cloudmason
   6. Run the following command to set up your org:
      • mason init-org -name MyOrg -region us-east-1
2. Set up a Local App Template
   1. Get a sample nodejs app template:
      • mason starter -p ./myDesktop/MyFirstApp -type asg -l node
3. Add an App

mason new-app -name MyFirstApp -type asg
mason new-instance -app MyFirstApp -domain myfirstapp.com -region us-east-2 -admin me@gmail.com
mason update-app -app MyFirstApp -v 1.0 -path ./myDesktop/HelloWorld
mason list-apps

1. Launch it

mason launch -app MyFirstApp -v 1.0 -domain myfirstapp.com
mason inspect -app MyFirstApp -domain myfirstapp.com -boot

1. Review It
   1. Visit the domain you specified. You'll see a login page.
   2. Check the email address you specified for a temp password. Use it to log in.
   3. After logging in, you'll see a "Hello World" page.

All Together

npm install -g cloudmason
mason init-org -name MyOrg -region us-east-1
mason starter -p ./myDesktop/MyFirstApp -type asg -l node
mason new-app -name MyFirstApp -type asg
mason new-instance -app MyFirstApp -domain myfirstapp.com -region us-east-2 -admin me@gmail.com
mason update-app -app MyFirstApp -v 1.0 -path ./myDesktop/MyFirstApp
mason launch -app MyFirstApp -v 1.0 -domain myfirstapp.com
mason inspect -app MyFirstApp -domain myfirstapp.com -boot

IMPORTANT!!!

• THIS APP DEPLOYS EC2 INSTANCES THAT ARE NOT FREE! IT WILL RESULT IN AWS CHARGES!
• Make sure to run delete-instance when you're done to avoid major surprises
• update-app will build an AMI, which may not be immediately available. Leave a few minutes between running update-app and launch
• Your web application must serve on localhost:8080
• Use inspect ! It will return all console output of your application - very useful for debugging

Commands

Run mason [command] -<options>

init-org

mason init-org -name -domain -region

Sets up base infrastructure in a new AWS organization. This command should only be run once. To set up the tool with an existing org, use set-org.

What it does

1. Retrieves the default VPC ID
2. Deploys a basic org infra stack
   1. S3 Bucket + policies for infra resources at infra.[domain]
   2. IAM Role, Instance Profile, and Security Group for Ec2 build agent
   3. SSM Parameters for oprg name, domain, instance profile, and security group

new-app

mason new-app -name -type -node -py

Params

Architecture Options

• asg: autoscaling group
• static: static site

Examples

mason new-app -name MyFirstApp -type asg -node

What it does

1. Builds a cloudformation stack with the appropriate boot script for nodejs or python
2. Uploads the cloudformation template to the S3 infrastructure bucket
3. Records the app name, type, and other key detail in SSM params

new-instance

mason new-instance -app -name -domain -region -admin -max -ins -env

Creates a new instance in a specified region. An instance is a deployment of an application. For example, MyFirstApp could have a test, UAT, and prod instance in us-east-1,us-east-2,and us-west-1.

Use -admin to specify the first admin user who will have access to set up other users.

Params

Examples

mason new-app -name MyFirstApp -type asg -node
mason new-instance -app MyFirstApp -name uat -domain test.cmason.io -region us-east-2
mason new-instance -app MyFirstApp -name beta -domain beta.cmason.io -region us-west-1

What it does

1. Requests an ACM certificate for the domain if none exists (for HTTPS)
2. Gets the default VPC ID and Subnets for the target region
3. Saves deployment params to SSM for use when deploying the cloud formation template:
   1. ACM Certificate ID
   2. VPC Id
   3. Subnets and hosted zone ID

update-app

mason update -app -v -path

Updates the code for the specified application. This command will build a new AMI and update cloudformation stacks to point to the new AMI. Path must lead to the root folder of your application. The bootscript will run with that directory as the root.

Params

Examples

mason update -app MyFirstApp -v 1.1 -path ./myfirstapp/src -stack ./myfirstapp/stack.json

What it does

1. Zips the folder (if not already zipped)
2. Updates the cloudformation stack.yml file and uploads to S3
3. Identifies the appropriate AWS Linux AMI ID for the base region
4. Launches an EC2 instance, waits until it's ready, and then builds an AMI with the updated code package
5. Terminates the EC2 instance
6. Updates SSM with the updated AMI ID and build number

launch

mason launch -app -v -i

Launches a specific version of an application to an instance. For example, launch (deploy) MyFirstApp version 1.2 to test.cmason.io.

Params

Examples

mason new-instance -app MyFirstApp -name uat -domain test.cmason.io -region us-east-2
mason update -app MyFirstApp -v 1.1 -path ./myfirstapp/src -stack ./myfirstapp/stack.jso
mason launch -app MyFirstApp -v 1.1 -i uat

What it does

1. Copies the AMI version created in the update command to the instance region
2. Deploys the updated cloudformation stack

update-stack

mason update-stack -app -v -default -stack

Updates the default cloudformation template, or updates the template for a specific version.

Params

Examples

Update version 5 with a new stack

mason update-stack -app MyFirstApp -v 1.0 -stack ../myfirstapp/stack.json

Update the default cloduformation template for all future versions

mason update-stack -app MyFirstApp -default -stack ../myfirstapp/stack.json

What it does

1. Uploads the specified stack file to S3

inspect

mason inspect -app -domain [-run or -boot]

Get stack status and EC2 console logs for an instance. Useful for debugging issues with application boot up. Console output will

To get run logs, the application must write logs to S3 in the logs/run folder. See the starter nodejs app for an example.

Params

Examples

mason inspect -app MyFirstApp -domain myfirstapp.com

starter

mason starter -type -l -path

Sets up a starter application template for the specified architecture and language

Params

Examples

mason starter -type asg -l node -path ../myfirstapp