From 5e19f898dd468e106d73ca9c547d36cc3d9ebcab Mon Sep 17 00:00:00 2001 From: rpigu-i <8628078+rpigu-i@users.noreply.github.com> Date: Thu, 11 Oct 2018 14:39:09 -0400 Subject: [PATCH 01/13] tst ci --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 08054c4..8639939 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ # Capsule + [![MIT Licensed](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/ModusCreateOrg/capsule/blob/OAS-15_documentation/LICENSE) Automated CLI for static web application hosting on AWS using S3 buckets. From e19e236873c7540e9d67b9bc7e9911d5bdf7fadb Mon Sep 17 00:00:00 2001 From: rpigu-i <8628078+rpigu-i@users.noreply.github.com> Date: Fri, 12 Oct 2018 08:53:11 -0400 Subject: [PATCH 02/13] Add in warning message to command line --- bin/capsule.js | 1 + 1 file changed, 1 insertion(+) diff --git a/bin/capsule.js b/bin/capsule.js index c0eb4f6..0e2ef9d 100755 --- a/bin/capsule.js +++ b/bin/capsule.js @@ -165,6 +165,7 @@ commander .command('deploy') .description('Builds out the web hosting infrastructure in one go') .action(function (options) { + console.log(chalk.bgRed.bold("DO NOT CANCEL THIS PROCESS UNTIL COMPLETED")) console.log("Executing project deployment") commander.type = options._name || undefined }); From 823e44c20d7e09ee6dd9fc570a1ffe9a00660497 Mon Sep 17 00:00:00 2001 From: rpigu-i <8628078+rpigu-i@users.noreply.github.com> Date: Fri, 12 Oct 2018 09:01:42 -0400 Subject: [PATCH 03/13] Update message in template --- config/capsule_init_questions.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config/capsule_init_questions.json b/config/capsule_init_questions.json index c51fa68..81fbe92 100644 --- a/config/capsule_init_questions.json +++ b/config/capsule_init_questions.json @@ -2,7 +2,7 @@ { "type": "input", "name": "ProjectName", - "message": "Enter your project name" + "message": "Enter your project name (Alphanumeric and underscore characters only)" }, { "type": "input", From afd03b15fecd53e34ed65a9df99451c58d3b67ed Mon Sep 17 00:00:00 2001 From: rpigu-i <8628078+rpigu-i@users.noreply.github.com> Date: Fri, 12 Oct 2018 15:31:33 -0400 Subject: [PATCH 04/13] Add stubs for new docs --- docs/advanced_use.md | 0 docs/contribute.md | 0 docs/templates.md | 0 3 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/advanced_use.md create mode 100644 docs/contribute.md create mode 100644 docs/templates.md diff --git a/docs/advanced_use.md b/docs/advanced_use.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/contribute.md b/docs/contribute.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/templates.md b/docs/templates.md new file mode 100644 index 0000000..e69de29 From c69507c228e7788579ff9a2b4d79ee30f02f73af Mon Sep 17 00:00:00 2001 From: rpigu-i <8628078+rpigu-i@users.noreply.github.com> Date: Mon, 15 Oct 2018 08:36:02 -0400 Subject: [PATCH 05/13] [issue-64] Start splitting up the readme file --- README.md | 229 +++++++------------------------------------ docs/advanced_use.md | 112 +++++++++++++++++++++ docs/templates.md | 74 ++++++++++++++ 3 files changed, 221 insertions(+), 194 deletions(-) diff --git a/README.md b/README.md index 8639939..ab56846 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,5 @@ # Capsule - [![MIT Licensed](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/ModusCreateOrg/capsule/blob/OAS-15_documentation/LICENSE) Automated CLI for static web application hosting on AWS using S3 buckets. @@ -35,7 +34,7 @@ npm install -g capsule You can now use `capsule` from your command line. -## Getting Started +## Quick Start - Configuring Your Environment In order to use Capsule you will need the following: @@ -67,7 +66,7 @@ A safe bet is to use `us-east-1` as this is the region that Capsule has been tes 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 +We a need directory to store this file, so create a new directory `.aws` under the root of your user *Mac/Linux* @@ -96,9 +95,9 @@ After creating these files, log into your AWS account. We now need to create an 5. Next click on your username in the table 6. When this loads, click on the `Security Credentials` tab 7. We can now create an Access Key by clking `Create Access Key` -8. Finally click `Show User Security Credentials` and copy the ID and value. +8. Finally click `Show User Security Credentials` and 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. +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` @@ -107,18 +106,18 @@ Now replace the `accessKeyId` value () with the value you co 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 `"`. +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. +Save the file. You are now ready to use Capsule to build out your static site. #### AWS Config - YAML setup 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 +Create a new directory `.aws` under the root of your user *Mac/Linux* @@ -153,9 +152,9 @@ After creating these files, log into your AWS account. We now need to create an 5. Next click on your username in the table 6. When this loads, click on the `Security Credentials` tab 7. We can now create an Access Key by clking `Create Access Key` -8. Finally click `Show User Security Credentials` and copy the ID and value. +8. Finally click `Show User Security Credentials` and 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. +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` @@ -182,35 +181,20 @@ region=us-east-1 output=json ``` -Save the file. +Save the file. Your credentials and configuration are now setup to use Capsule. -### Your website configuration - -Capsule supports a number of command line parameters to allow you to configure your web site. - -In addition to this, you can use a JSON configuration file, containing these values. - -An example can be found in the `config/capsule.json` file in the capsule repository. - -When loading configuration options, the JSON config is loaded first, if specified. Following this any command line -parameters are then loaded. Command line parameters will override any parameters specified in the JSON file. - -An example can be seen here: - -``` -./bin/capsule.js create --project-name "exampledotcom" --dom example.com --subdom app --url https://github.com/ExampleCom/exampledotcom --config ~/.aws/config.json --site_config='{"WebsiteCode":"./build"}' --site_config_file=./config/capsule.json ci -``` - -In this example the value of the `--site_config` flag will overwrite the the key value pair specified in the `--site_config_file` JSON file. -Thus if `WebsiteCode` is defined in `capsule.json` it's value will be overridden with `./build`. +## Quick Start - Configure Your Project -You can always check what command line parameters are available by running the `capsule -h` command. +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 paramter. +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: @@ -229,7 +213,7 @@ npm build dev ; npm test ### Project Names -During the setup of your site you will need to define a project name. This will be used to name the +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: @@ -237,11 +221,24 @@ You can find these here: https://docs.aws.amazon.com/AmazonS3/latest/dev/BucketRestrictions.html + +## Quick Start - Deploy Your Project + +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. + ### Authorizing your certificate In order to authorize your certificate you will need to log into the AWS console. -Depending on whether you are using DNS or Email authroitzation you will need to follow the relevant steps below. +Depending on whether you are using DNS or Email authorization you will need to follow the relevant steps below. ### CloudFront waiting time @@ -288,102 +285,20 @@ Triggers: Webhook: yes ``` -In this case, the user will need Admin permissions. +In this case, the user will need Admin permissions. You will need to create a webhook in GitHub. -### How to use it? - -The `ci` tool can be executed from the command line in order to setup the -CodeBuild process. Located in this repository are two CodeBUild files: - -1. `codebuild_capsule.cf` - this contains the CodeBuild CF templates for this project -2. `codebuild_project.cf` - which provides a template for the Capsule user to use for their own project - -In addition to the `ci` tool the CodeBuild cf templates can also be executed from the aws cli. - -From the CLI it can be used like this: - -```sh -aws cloudformation create-stack \ - --stack-name \ - --template-body file:///ci/.cf \ - --parameters ParameterKey=CodeBuildProjectCodeName,ParameterValue= \ - ParameterKey=RepositoryURL,ParameterValue= \ - ParameterKey=BuildSpecLocation,ParameterValue= -``` - -Example: - -```sh -aws cloudformation create-stack \ - --stack-name moduscreate-labs \ - --template-body file:///ci/codebuild_project.cf \ - --parameters ParameterKey=CodeBuildProjectCodeName,ParameterValue=labs \ - ParameterKey=RepositoryURL,ParameterValue=https://github.com/ModusCreateOrg/labs.git -``` - -#### Supported parameters: - -- *CodeBuildProjectCodeName*: CodeBuild Project codename. -- *RepositoryURL*: HTTPS URL for the Git repository. This should be a valid repository HTTPS URL. -- *RepositoryType*: `CODECOMMIT`|`CODEPIPELINE`|`GITHUB`|`GITHUB_ENTERPRISE`|`BITBUCKET`|`S3`. Default: `GITHUB`. -- *EnvironmentImage*: Image to use for running a container where the build will execute. Needs to respect the format `/:`. Default: `aws/codebuild/ubuntu-base:14.04` -- *ComputeType*: `BUILD_GENERAL1_SMALL` (Small 3 GB memory, 2 vCPU) | `BUILD_GENERAL1_MEDIUM` (Medium 7 GB memory, 4 vCPU) | `BUILD_GENERAL1_LARGE` (large 15 GB memory, 8 vCPU). Default: `BUILD_GENERAL1_SMALL`. -- *BuildSpecLocation*: Path of the file `buildspec.yml` to use (Defaults to `/buildspec.yml` - - -### Using the capsule cli: - -The capsule cli is a NodeJS cli app with the intention to simplify the generation of the hosting infrastructure and ci infrastructure. For nested stacks, it requires to generate a base s3 bucket. This can be generated in the following way: - -```sh -$ ./capsule create --project-name s3 -``` - -For getting the complete list of options, just enter `--help`: - -```sh -$ ./bin/capsule.js --help - - Usage: capsule [options] - - Options: - - -V, --version Output the version number - init Builds out the web hosting infrastructure in one go - create Initializes the s3 bucket required to store nested stack templates - update Updates the templates into the s3 bucket and runs the nested stack - delete Delete the s3 bucket contents - -n, --project-name Push cf templates to the s3 bucket, and creates it if it does not exist - -c, --config Load the configuration from the specified path - -p, --aws-profile The AWS profile to use - -u, --url The source control URL to use - -sc, --site_config A JSON object contianing site configuration, overrides values defined in site config file - -scf, --site_config_file Custom configuration file used in CodeBuild for building the static site - -d, --remove-cf-bucket Remove the bucket used for storing the nested templates - -v, --verbose Verbose output - -h, --help output usage information - -``` - -To kick off building out a project with a single command, you can use the `init` option. The example below demonstrates this: - -``` -./bin/capsule.js init --project-name "exampledotcom" --dom example.com --subdom app --url https://github.com/ExampleCom/exampledotcom --config ~/.aws/config.json --site_config='{"WebsiteCode":"."}' --site_config_file=./config/capsule.json -``` - - #### Domain configuration 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 +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: +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: * webmaster@example.com * admin@example.com @@ -391,7 +306,7 @@ Open up the drop-down arrow for the domain and follow the insturctions provived * administrator@example.com * hostmaster@example.com -Wjere `example.com` is the domain you passed to the cli tool. +Where `example.com` is the domain you passed to the cli tool. ### Future steps: @@ -400,80 +315,6 @@ Wjere `example.com` is the domain you passed to the cli tool. - Add in CloudTrail support for debugging -## Templates - -Capsule is made up of multiple YAML based Cloud Formation templates. - -You can read more about AWS CloudFormation on the AWS official page: - -https://aws.amazon.com/cloudformation/ - -A brief description of each is provided as follows. - -### Certificates - template.certificate.yaml - -This file handles the certificate manager portion -of the CloudFormation configuration. - -You can read more about AWS Certificate Manager here: - -https://aws.amazon.com/certificate-manager/ - - -### CloudFront - template.cloudfront.yaml - -This file contains the list of parameters required by our -CloudFormation Stack including Error codes, HTTP versions and SSL supported method. -CloudFront acts as a CDN. More documentation can be found at the AWS page here: - -https://aws.amazon.com/cloudfront/ - -### CloudFront Origin Access Identity - template.cfoai.yaml - -The CFOAI template contains the configuration required -for CloudFront Origin Access Identity. - -You can read more about CFOAI here: - -https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-restricting-access-to-s3.html - - -### Route 53 - template.route53.yaml - -Here you can find the Route 53 configuration for the static website -project. - -To learn more about Route 53 you can read the official documents here: - -https://aws.amazon.com/route53/ - - -### S3 - template.s3.yaml - -Amazon S3 bucket configuration can be found here. -The S3 bucket is where the static resources will be uploaded to and hosted -from. - -To learn more visit the official webpage here: - -https://aws.amazon.com/s3/ - -### CodeBuild - codebuild_project.cf - -Included in this project are two CodeBuild Cloud Formation templates: - -1. The template for Capsule itself -2. A parameterized template for use with your own project. - -CodeBuild configuration to handle: - -1. Creating environment to check project into -2. Pull code from GitHub/Source control -3. Install code -4. Run tests -5. Create build -6. Upload build to S3 bucket -7. Setup trigger so that new pushes to master are built/test/deployed ## Modus Create diff --git a/docs/advanced_use.md b/docs/advanced_use.md index e69de29..9cd409a 100644 --- a/docs/advanced_use.md +++ b/docs/advanced_use.md @@ -0,0 +1,112 @@ +# Advanced use + +The following document provides a guide to the advanced features +provided by capsule. + + +## Your website configuration + +Capsule supports a number of command line parameters to allow you to configure your web site. + +In addition to this, you can use a JSON configuration file, containing these values. + +An example can be found in the `config/capsule.json` file in the capsule repository. + +When loading configuration options, the JSON config is loaded first, if specified. Following this any command line +parameters are then loaded. Command line parameters will override any parameters specified in the JSON file. + +An example can be seen here: + +``` +./bin/capsule.js create --project-name "exampledotcom" --dom example.com --subdom app --url https://github.com/ExampleCom/exampledotcom --config ~/.aws/config.json --site_config='{"WebsiteCode":"./build"}' --site_config_file=./config/capsule.json ci +``` + +In this example the value of the `--site_config` flag will overwrite the the key value pair specified in the `--site_config_file` JSON file. +Thus if `WebsiteCode` is defined in `capsule.json` it's value will be overridden with `./build`. + + +You can always check what command line parameters are available by running the `capsule -h` command. + + +## Advanced CLI use + +The capsule cli is a NodeJS cli app with the intention to simplify the generation of the hosting infrastructure and ci infrastructure. For nested stacks, it requires to generate a base s3 bucket. This can be generated in the following way: + +```sh +$ ./capsule create --project-name s3 +``` + +For getting the complete list of options, just enter `--help`: + +```sh +$ ./bin/capsule.js --help + + Usage: capsule [options] + + Options: + + -V, --version Output the version number + init Builds out the web hosting infrastructure in one go + create Initializes the s3 bucket required to store nested stack templates + update Updates the templates into the s3 bucket and runs the nested stack + delete Delete the s3 bucket contents + -n, --project-name Push cf templates to the s3 bucket, and creates it if it does not exist + -c, --config Load the configuration from the specified path + -p, --aws-profile The AWS profile to use + -u, --url The source control URL to use + -sc, --site_config A JSON object contianing site configuration, overrides values defined in site config file + -scf, --site_config_file Custom configuration file used in CodeBuild for building the static site + -d, --remove-cf-bucket Remove the bucket used for storing the nested templates + -v, --verbose Verbose output + -h, --help output usage information + +``` + +To kick off building out a project with a single command, you can use the `init` option. The example below demonstrates this: + +``` +./bin/capsule.js init --project-name "exampledotcom" --dom example.com --subdom app --url https://github.com/ExampleCom/exampledotcom --config ~/.aws/config.json --site_config='{"WebsiteCode":"."}' --site_config_file=./config/capsule.json +``` + + + + +### Advanced CI use + +The `ci` tool can be executed from the command line in order to setup the +CodeBuild process. Located in this repository are two CodeBUild files: + +1. `codebuild_capsule.cf` - this contains the CodeBuild CF templates for this project +2. `codebuild_project.cf` - which provides a template for the Capsule user to use for their own project + +In addition to the `ci` tool the CodeBuild cf templates can also be executed from the aws cli. + +From the CLI it can be used like this: + +```sh +aws cloudformation create-stack \ + --stack-name \ + --template-body file:///ci/.cf \ + --parameters ParameterKey=CodeBuildProjectCodeName,ParameterValue= \ + ParameterKey=RepositoryURL,ParameterValue= \ + ParameterKey=BuildSpecLocation,ParameterValue= +``` + +Example: + +```sh +aws cloudformation create-stack \ + --stack-name moduscreate-labs \ + --template-body file:///ci/codebuild_project.cf \ + --parameters ParameterKey=CodeBuildProjectCodeName,ParameterValue=labs \ + ParameterKey=RepositoryURL,ParameterValue=https://github.com/ModusCreateOrg/labs.git +``` + +#### Supported parameters: + +- *CodeBuildProjectCodeName*: CodeBuild Project codename. +- *RepositoryURL*: HTTPS URL for the Git repository. This should be a valid repository HTTPS URL. +- *RepositoryType*: `CODECOMMIT`|`CODEPIPELINE`|`GITHUB`|`GITHUB_ENTERPRISE`|`BITBUCKET`|`S3`. Default: `GITHUB`. +- *EnvironmentImage*: Image to use for running a container where the build will execute. Needs to respect the format `/:`. Default: `aws/codebuild/ubuntu-base:14.04` +- *ComputeType*: `BUILD_GENERAL1_SMALL` (Small 3 GB memory, 2 vCPU) | `BUILD_GENERAL1_MEDIUM` (Medium 7 GB memory, 4 vCPU) | `BUILD_GENERAL1_LARGE` (large 15 GB memory, 8 vCPU). Default: `BUILD_GENERAL1_SMALL`. +- *BuildSpecLocation*: Path of the file `buildspec.yml` to use (Defaults to `/buildspec.yml` diff --git a/docs/templates.md b/docs/templates.md index e69de29..cf8fe9b 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -0,0 +1,74 @@ +# Templates + +Capsule is made up of multiple YAML based Cloud Formation templates. + +You can read more about AWS CloudFormation on the AWS official page: + +https://aws.amazon.com/cloudformation/ + +A brief description of each is provided as follows. + +### Certificates - template.certificate.yaml + +This file handles the certificate manager portion +of the CloudFormation configuration. + +You can read more about AWS Certificate Manager here: + +https://aws.amazon.com/certificate-manager/ + + +### CloudFront - template.cloudfront.yaml + +This file contains the list of parameters required by our +CloudFormation Stack including Error codes, HTTP versions and SSL supported method. +CloudFront acts as a CDN. More documentation can be found at the AWS page here: + +https://aws.amazon.com/cloudfront/ + +### CloudFront Origin Access Identity - template.cfoai.yaml + +The CFOAI template contains the configuration required +for CloudFront Origin Access Identity. + +You can read more about CFOAI here: + +https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-restricting-access-to-s3.html + + +### Route 53 - template.route53.yaml + +Here you can find the Route 53 configuration for the static website +project. + +To learn more about Route 53 you can read the official documents here: + +https://aws.amazon.com/route53/ + + +### S3 - template.s3.yaml + +Amazon S3 bucket configuration can be found here. +The S3 bucket is where the static resources will be uploaded to and hosted +from. + +To learn more visit the official webpage here: + +https://aws.amazon.com/s3/ + +### CodeBuild - codebuild_project.cf + +Included in this project are two CodeBuild Cloud Formation templates: + +1. The template for Capsule itself +2. A parameterized template for use with your own project. + +CodeBuild configuration to handle: + +1. Creating environment to check project into +2. Pull code from GitHub/Source control +3. Install code +4. Run tests +5. Create build +6. Upload build to S3 bucket +7. Setup trigger so that new pushes to master are built/test/deployed From 84246b01924ae7caf54e2e20303f11fe1bbe8d26 Mon Sep 17 00:00:00 2001 From: rpigu-i <8628078+rpigu-i@users.noreply.github.com> Date: Tue, 16 Oct 2018 08:59:40 -0400 Subject: [PATCH 06/13] Update to advanced_use.md file --- docs/advanced_use.md | 42 +++++++++++++++--------------------------- 1 file changed, 15 insertions(+), 27 deletions(-) diff --git a/docs/advanced_use.md b/docs/advanced_use.md index 9cd409a..0a866b9 100644 --- a/docs/advanced_use.md +++ b/docs/advanced_use.md @@ -8,9 +8,7 @@ provided by capsule. Capsule supports a number of command line parameters to allow you to configure your web site. -In addition to this, you can use a JSON configuration file, containing these values. - -An example can be found in the `config/capsule.json` file in the capsule repository. +In addition to this, you can use a JSON configuration file as generated by the `init` command, containing these values. When loading configuration options, the JSON config is loaded first, if specified. Following this any command line parameters are then loaded. Command line parameters will override any parameters specified in the JSON file. @@ -18,7 +16,7 @@ parameters are then loaded. Command line parameters will override any parameters An example can be seen here: ``` -./bin/capsule.js create --project-name "exampledotcom" --dom example.com --subdom app --url https://github.com/ExampleCom/exampledotcom --config ~/.aws/config.json --site_config='{"WebsiteCode":"./build"}' --site_config_file=./config/capsule.json ci +./bin/capsule.js create --project-name "exampledotcom" --dom example.com --subdom app --url https://github.com/ExampleCom/exampledotcom --config ~/.aws/config.json --site_config='{"WebsiteCode":"./build"}' --site_config_file=./my_config/capsule.json ci ``` In this example the value of the `--site_config` flag will overwrite the the key value pair specified in the `--site_config_file` JSON file. @@ -30,7 +28,7 @@ You can always check what command line parameters are available by running the ` ## Advanced CLI use -The capsule cli is a NodeJS cli app with the intention to simplify the generation of the hosting infrastructure and ci infrastructure. For nested stacks, it requires to generate a base s3 bucket. This can be generated in the following way: +The capsule cli is a NodeJS cli app with the intention to simplify the generation of the hosting infrastructure and ci infrastructure. For nested stacks, it requires the generation of a base s3 bucket. This can be generated in the following way: ```sh $ ./capsule create --project-name s3 @@ -41,40 +39,30 @@ For getting the complete list of options, just enter `--help`: ```sh $ ./bin/capsule.js --help - Usage: capsule [options] + Usage: capsule [options] [command] Options: - -V, --version Output the version number - init Builds out the web hosting infrastructure in one go - create Initializes the s3 bucket required to store nested stack templates - update Updates the templates into the s3 bucket and runs the nested stack - delete Delete the s3 bucket contents - -n, --project-name Push cf templates to the s3 bucket, and creates it if it does not exist - -c, --config Load the configuration from the specified path - -p, --aws-profile The AWS profile to use - -u, --url The source control URL to use - -sc, --site_config A JSON object contianing site configuration, overrides values defined in site config file - -scf, --site_config_file Custom configuration file used in CodeBuild for building the static site - -d, --remove-cf-bucket Remove the bucket used for storing the nested templates - -v, --verbose Verbose output - -h, --help output usage information + -V, --version output the version number + -v, --verbose verbose output + -h, --help output usage information -``` + Commands: -To kick off building out a project with a single command, you can use the `init` option. The example below demonstrates this: + init Define the project parameters + deploy Builds out the web hosting infrastructure in one go + remove [options] Removes the whole of the web hosting infrastructure, including files in S3 buckets + create [options] Initializes the s3 bucket required to store nested stack templates takes: s3, ci or web + update [options] Updates the templates into the s3 bucket and runs the nested stack takes: s3, ci or web + delete [options] Deletes the s3 bucket contents takes: s3, ci or web ``` -./bin/capsule.js init --project-name "exampledotcom" --dom example.com --subdom app --url https://github.com/ExampleCom/exampledotcom --config ~/.aws/config.json --site_config='{"WebsiteCode":"."}' --site_config_file=./config/capsule.json -``` - - ### Advanced CI use The `ci` tool can be executed from the command line in order to setup the -CodeBuild process. Located in this repository are two CodeBUild files: +CodeBuild process. Located in this repository are two CodeBuild files: 1. `codebuild_capsule.cf` - this contains the CodeBuild CF templates for this project 2. `codebuild_project.cf` - which provides a template for the Capsule user to use for their own project From ab8484fda799ad644ad964eb553e65e9d75b367d Mon Sep 17 00:00:00 2001 From: rpigu-i <8628078+rpigu-i@users.noreply.github.com> Date: Tue, 16 Oct 2018 10:19:14 -0400 Subject: [PATCH 07/13] Update readme doc --- README.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/README.md b/README.md index ab56846..b97a697 100644 --- a/README.md +++ b/README.md @@ -314,6 +314,19 @@ Where `example.com` is the domain you passed to the cli tool. - The CI infrastructure for Capsule will be evolving soon to use codepipeline to execute several integration tests the cloudformation templates and the cli with different node versions. - Add in CloudTrail support for debugging +## Advanced Options + +Capsule comes with a number of advanced options. These allow: + +1. A more granular deployment process +2. Overridding default settings in the capsule.json with command line values + +To read me please check out the documentation here. + +### Templates + +To learn more about the CloudFormation templates that make up a portion of the capsule project +please refer to the template documentation here. ## Modus Create From 3bf5cef1c6dcb8d13a51748ad86eb5ecfbf5cd8c Mon Sep 17 00:00:00 2001 From: rpigu-i <8628078+rpigu-i@users.noreply.github.com> Date: Tue, 16 Oct 2018 10:22:22 -0400 Subject: [PATCH 08/13] Add links to readme --- README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b97a697..6fe9462 100644 --- a/README.md +++ b/README.md @@ -321,13 +321,16 @@ Capsule comes with a number of advanced options. These allow: 1. A more granular deployment process 2. Overridding default settings in the capsule.json with command line values -To read me please check out the documentation here. +To read me please check out the documentation [here](docs/advanced_use.md). ### Templates To learn more about the CloudFormation templates that make up a portion of the capsule project -please refer to the template documentation here. +please refer to the template documentation [here](docs/templates.md). +## Contibute to this project + +To learn about our contributor guidelines, please check out the documentation [here](docs/contribute.md) ## Modus Create From acffdc883cc4c8c5eb82b6bc9d98bc5058157ee2 Mon Sep 17 00:00:00 2001 From: rpigu-i <8628078+rpigu-i@users.noreply.github.com> Date: Tue, 16 Oct 2018 10:30:50 -0400 Subject: [PATCH 09/13] Update readme file layout --- README.md | 45 ++++++++++++++++++++------------------------- 1 file changed, 20 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 6fe9462..9d6747f 100644 --- a/README.md +++ b/README.md @@ -232,7 +232,7 @@ 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. +deploy command, please refer to the [templates read me](docs/templates.md) file. ### Authorizing your certificate @@ -241,6 +241,25 @@ 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. +#### Domain configuration + +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: + +* webmaster@example.com +* admin@example.com +* postmaster@example.com +* administrator@example.com +* hostmaster@example.com + +Where `example.com` is the domain you passed to the cli tool. + + ### CloudFront waiting time Once the CloudFormation templates are kicked off the CloudFront stack process, you can expect to wait around ~20 mins for this @@ -290,30 +309,6 @@ In this case, the user will need Admin permissions. You will need to create a webhook in GitHub. -#### Domain configuration - -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: - -* webmaster@example.com -* admin@example.com -* postmaster@example.com -* administrator@example.com -* hostmaster@example.com - -Where `example.com` is the domain you passed to the cli tool. - -### Future steps: - -- The CI for the hosted project will still be using codebuild -- The CI infrastructure for Capsule will be evolving soon to use codepipeline to execute several integration tests the cloudformation templates and the cli with different node versions. -- Add in CloudTrail support for debugging - ## Advanced Options Capsule comes with a number of advanced options. These allow: From 867c340dde19ec94b9aef09938d42e33370b189a Mon Sep 17 00:00:00 2001 From: rpigu-i <8628078+rpigu-i@users.noreply.github.com> Date: Tue, 16 Oct 2018 10:33:41 -0400 Subject: [PATCH 10/13] Add link to webhooks --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9d6747f..f936c49 100644 --- a/README.md +++ b/README.md @@ -306,7 +306,7 @@ Triggers: In this case, the user will need Admin permissions. -You will need to create a webhook in GitHub. +You will need to create a [webhook in GitHub](https://developer.github.com/webhooks/). ## Advanced Options From 16d2686732bfb37222980e3c3f89503e331a348e Mon Sep 17 00:00:00 2001 From: rpigu-i <8628078+rpigu-i@users.noreply.github.com> Date: Tue, 16 Oct 2018 10:39:47 -0400 Subject: [PATCH 11/13] Update advanced use docs --- docs/advanced_use.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/docs/advanced_use.md b/docs/advanced_use.md index 0a866b9..d160990 100644 --- a/docs/advanced_use.md +++ b/docs/advanced_use.md @@ -34,7 +34,28 @@ The capsule cli is a NodeJS cli app with the intention to simplify the generatio $ ./capsule create --project-name s3 ``` -For getting the complete list of options, just enter `--help`: +Once this bucket is in place, the web infrastructure can then be created using the `web` command line option. + +For example: + +```sh + $ ./capsule create --project-name web +``` + +Having setup the infrastructure, you can then add in the CI pipeline as follows: + + +```sh + $ ./capsule create --project-name ci +``` + + +Not all the examples above, have assumed a `capsule.js` file is present, and that the ProjectName value has +been overwritten by the `--project-name` parameter. + +In addition to the `create` command, Capsule also supports an `update` and `delete` command. + +For getting the complete list of options and how they are used, just enter `--help`: ```sh $ ./bin/capsule.js --help From bc4a4812d5f7d0b40730a65365c74d093d1c8c17 Mon Sep 17 00:00:00 2001 From: rpigu-i <8628078+rpigu-i@users.noreply.github.com> Date: Tue, 16 Oct 2018 10:44:03 -0400 Subject: [PATCH 12/13] Added CoC and contribute docs --- docs/CODE_OF_CONDUCT.md | 59 +++++++++++++++++++++++++++++++++++++++++ docs/contribute.md | 15 +++++++++++ 2 files changed, 74 insertions(+) create mode 100644 docs/CODE_OF_CONDUCT.md diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..f52acda --- /dev/null +++ b/docs/CODE_OF_CONDUCT.md @@ -0,0 +1,59 @@ +# Open Source Code Of Conduct + +This code of conduct outlines our expectations for participants within the Modus Create community, as well as steps to reporting unacceptable behavior. We are committed to providing a welcoming and inspiring community for all and expect our code of conduct to be honored. Anyone who violates this code of conduct may be banned from the community. + +Our open source community strives to: + +#### Be friendly and patient. + +#### Be welcoming + +We strive to be a community that welcomes and supports people of all backgrounds and identities. This includes, but is not limited to members of any race, ethnicity, culture, national origin, colour, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, religion, and mental and physical ability. + +#### Be considerate + +Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and you should take those consequences into account when making decisions. Remember that we’re a world-wide community, so you might not be communicating in someone else’s primary language. + +#### Be respectful + +Not all of us will agree all the time, but disagreement is no excuse for poor behavior and poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It’s important to remember that a community where people feel uncomfortable or threatened is not a productive one. +Be careful in the words that you choose: we are a community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put down other participants. Harassment and other exclusionary behavior aren’t acceptable. This includes, but is not limited to: + +* Violent threats or language directed against another person. +* Discriminatory jokes and language. +* Posting sexually explicit or violent material. +* Posting (or threatening to post) other people’s personally identifying information (“doxing”). +* Personal insults, especially those using racist or sexist terms. +* Unwelcome sexual attention. +* Advocating for, or encouraging, any of the above behavior. +* Repeated harassment of others. In general, if someone asks you to stop, then stop. + +#### When we disagree, try to understand why + +Disagreements, both social and technical, happen all the time. It is important that we resolve disagreements and differing views constructively. + +#### Remember that we’re different + +The strength of our community comes from its diversity, people from a wide range of backgrounds. Different people have different perspectives on issues. Being unable to understand why someone holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that it is human to err and blaming each other doesn’t get us anywhere. Instead, focus on helping to resolve issues and learning from mistakes. + +This code is not exhaustive or complete. It serves to distill our common understanding of a collaborative, shared environment, and goals. We expect it to be followed in spirit as much as in the letter. + +## Diversity Statement + +We encourage everyone to participate and are committed to building a community for all. Although we may not be able to satisfy everyone, we all agree that everyone is equal. Whenever a participant has made a mistake, we expect them to take responsibility for it. If someone has been harmed or offended, it is our responsibility to listen carefully and respectfully, and do our best to right the wrong. + +Although this list cannot be exhaustive, we explicitly honor diversity in age, gender, gender identity or expression, culture, ethnicity, language, national origin, political beliefs, profession, race, religion, sexual orientation, socioeconomic status, and technical ability. We will not tolerate discrimination based on any of the protected characteristics above, including participants with disabilities. + +## Reporting Issues + +If you experience or witness unacceptable behavior—or have any other concerns—please report it by contacting us via `opensource@moduscreate.com`. All reports will be handled with discretion. In your report please include: + +* Your contact information. +* Names (real, nicknames, or pseudonyms) of any individuals involved. If there are additional witnesses, please include them as well. Your account of what occurred, and if you believe the incident is ongoing. If there is a publicly available record (e.g. a mailing list archive or a public IRC logger), please include a link. +* Any additional information that may be helpful. + +After filing a report, a representative will contact you personally. If the person who is harassing you is part of the response team, they will recuse themselves from handling your incident. A representative will then review the incident, follow up with any additional questions, and make a decision as to how to respond. We will respect confidentiality requests for the purpose of protecting victims of abuse. + +Anyone asked to stop unacceptable behavior is expected to comply immediately. If an individual engages in unacceptable behavior, the representative may take any action they deem appropriate, up to and including a permanent ban from our community without warning. + +This Code Of Conduct follows the [template](http://todogroup.org/opencodeofconduct/) established by the [TODO Group](http://todogroup.org/). diff --git a/docs/contribute.md b/docs/contribute.md index e69de29..ab482a1 100644 --- a/docs/contribute.md +++ b/docs/contribute.md @@ -0,0 +1,15 @@ +# Contribute to this project + +# Contributing to Project + +### Code of Conduct + +Modus has adopted a [Code of Conduct](./CODE_OF_CONDUCT.md) that we expect project participants to adhere to. + +### Submitting a Pull Request + +If you are a first time contributor, you can learn how from this _free_ series [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github) + +### License + +By contributing, you agree that your contributions will belicensed under it's [license](../LICENSE) From 2ac7f609caada1f4cf9effbb8d0f01ad13655cae Mon Sep 17 00:00:00 2001 From: rpigu-i <8628078+rpigu-i@users.noreply.github.com> Date: Tue, 16 Oct 2018 10:46:03 -0400 Subject: [PATCH 13/13] Fox duplicate title --- docs/contribute.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/contribute.md b/docs/contribute.md index ab482a1..5b58b02 100644 --- a/docs/contribute.md +++ b/docs/contribute.md @@ -1,5 +1,3 @@ -# Contribute to this project - # Contributing to Project ### Code of Conduct