@webnuts/catapult v0.7.7

catapult

A catapult is a ballistic device used to launch a projectile a great distance without the aid of explosive devices

Amazon AWS is awesome!

Catapult uses the following aAmazon AWS services:

• S3
• CodeBuild
• CodePipeline
• CloudWatch
• Route 53
• CloudFront

Installation

npm install -g @webnuts/catapult

Requirements

Your Catapult projects are required to contain the following files.

~/catapult-build.json

The file must contain the following key:

• build (an array of strings representing commands to execute in the build phase)
• output (a string representing where the output files are located)

Additionally, you may also specify keys for the phases: install, pre_build, and post_build. These work similarly to build.

Note: This file is required since it specifies the command which AWS CodeBuild will use to build the command, and which output it can expect from it.

Example catapult-build.json

{
  "install": [
    "npm install"
  ],
  "build": [
    "ember build"
  ],
  "output": "dist"
}

Note: It is important that the output directory contains an index.html-file if the project is a static website, since all trafic will be redirected to this.

Credentials

Since Catapult Amazon services, you need to register your credentials within the CLI so that we have access to make the necessary changes.

Amazon

To be implemented

Commands

You can call catapult <command> --help to find out more about a particular command.

TODO: Insert command list here

Initializing a Catapult project

catapult initialize <name>

Initializes a brand new Catapult project. This will setup Amazon services.

Destroying a Catapult project

catapult destroy <name> [--confirm <confirm-string>]

Destroys a Catapult project by deleting the corresponding Amazon services.

Add the --confirm flag to comfirm the action. The confirm-string needs to be the name of the repository you are currently working in.

⚠️ This will delete every configuration associated with the Catapult project. This command is very destructive. Use with caution.

Deployments

catapult deployments [--limit=<limit>] [--offset=<offset>]

Lists the latest deployments made to the branch you are currently working on unless another branch is specified using the --branch flag. This information includes: Build number, status and duration

Use the --limit flag to specify how many builds you want to see.

Use the --offset flag to specify where to list the builds from.

catapult deployment [deployment-number | deployment-id | 'LATEST'] [--wait]

Shows details about the latest deployment made to the branch you are currently working unless another branch is specified using the --branch flag.

You may specify a particular deployment-number (e.g. 14) or deployment-id (e.g. 7f3feae8-a830-4f7b-8b1c-02f73452e328) to lookup a particular deployment (use catapult deployments to find these).

You may include a branch to lookup deployments on that branch.

Specify the --wait flag to refresh the deployment information untill the build is no longer IN_PROGRESS.

Deploying

catapult deploy 

Runs the deployment pipeline for the branch you are currently working on unless another branch is specified using the --branch flag.

Undeploying

catapult undeploy

Undeploys the branch you are currently working on unless another branch is specified using the --branch flag.

Rolling back to a previous deployment

catapult rollback [(--steps <steps> | --deployment <identifier>)]

Rolls back the branch you are working on to the previous deployment unless another branch is specified using the --branch flag.

You may rollback a number of deployments by providing the --steps <steps> flag, e.g. --steps 7

You may rollback to a specific deployment by providing the --deployment <identifier> flag, e.g. --deployment 7f3feae8-a830-4f7b-8b1c-02f73452e328 or --deployment 7

💡 See a list of deployments using the catapult deployments command.

Hosts

catapult hosts 

Lists the hosts (domain names) associated with the Catapult project.

Adding Hosts

catapult hosts:add <host> [--confirm]

Adds a host to the Catapult project, e.g. example.com or development.example.com for the branch you are currently working on unless another is specified using the --branch flag.

Use the --confirm flag to confirm the action.

Removing Hosts

catapult hosts:remove <host> [--confirm]

Removes a hosts to the catapult project.

Add the --confirm flag to comfirm the action. The confirm-string needs to be the name of the repository you are currently working in.

Limiting Requests

catapult limits 

Lists limits for the Catapult project.

Configuring limits

catapult limits:configure

Configures the limits for the Catapult project.

Here you will be able to configure:

• Caching policies (TTL) for CloudFront distributions
• ... (rest is not documented yet)

Credentials

⚠️ You should treat these credentials like your password. Do not version control them.

catapult credentials [--unhide | --clear]

Will output a list of the registered credentials you have registered within the CLI.

Access tokens can be fully displayed by using the --unhide flag.

When in a hurry, all access tokens can be removed using the --clear flag.

Configuring credentials

catapult credentials:configure [amazon]

Prompts you for the required credentials required to manage Catapult projects.

💡 To generate these access tokens, please refer to the credentials section.

Catapult Management Commands

The following commands are used to maintain and develop on Catapult. Use with caution.

Generating a buildspec.yml file for a Catapult project

catapult build [phase]

Will build the projects according to the specifications found in ~/catapult-build.json.

Specify a phase to only execute commands in that phase. Valid values are install, pre_build, build, and, post_build.

Note: Running this command will have zero influence on AWS.

Updating Catapult projects

catapult update [--all, --lambda]

Will re-initialize AWS services such that they get the latest code.

You may specify the --all flag to update all Catapult project.

Specify the -lambda flag to update only the Lambda functions.

Managing CloudFront distributions

catapult distributions

Will list information about all CloudFront distributions, e.g. their status, url, etc.

catapult distributions:sync

Will syncronize CloudFront distributions for the branch you are currently working on. Will also remove any unused/old distributions for the repository.

Managing Route53 records

catapult records

Will list information about all Route53 records

catapult records:sync

Will syncronize Route53 records for the branch you are currently working on. Will also remove any unused/old records for the repository.