refactor readme

README.md

@@ -3,7 +3,7 @@
 The intention of this sample is to put together [DevOps](https://aws.amazon.com/training/learn-about/devops/) CI/CD best practices and provide a sample for the [AWS CodePipeline](https://aws.amazon.com/codepipeline/).
 After implementing this sample, you will get an AWS CodePipeline with linting, testing, security check, deployment and post-deployment process.
 
-Target technology stack  
+### Target technology stack
 
 After execution of the CDK code, following type of resources gets generated:
 
@@ -13,7 +13,7 @@ CodePipeline is a continuous delivery service. It is triggered by code checked i
 
 * CloudFormation stacks
 
-The cloud formation stacks groups various AWS services in a collection which can be managed as a single unit. 
+The cloud formation stacks groups various AWS services in a collection which can be managed as a single unit.
 This stack creates the CodeCommit repository and the CI/CD pipeline consisting of CodePipeline. As a first step, on execution of CDK deploy command, "SampleRepository" gets created.
 
 ## Architecture
@@ -39,47 +39,55 @@ Limitation
 
 This project is based on [AWS CDK v2](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html) and uses TypeScript as a primary language.
 
-### MacOS installing
+### Installation
 
-Use following command to install required software for MacOS:
-```
+#### MacOS or Linux
+
+If you are using MacOS, you can install the prerequisites by running the following command in your preferred terminal or also on Linux using [homebrew for Linux](https://docs.brew.sh/Homebrew-on-Linux):
+
+```bash
 nvm install 16.3
 brew install git-remote-codecommit
 brew install ruby brew-gem
 brew gem install cfn-nag
 ```
+#### AWS Cloud9
 
-### AWS Cloud9 installing
+If you are using AWS [Cloud9](https://aws.amazon.com/cloud9/), you can use following command to install the prerequisites:
 
-Use following command to install required software for [Cloud9](https://aws.amazon.com/cloud9/):
-```
+```bash
 gem install cfn-nag
 ```
+Note: Cloud9 should have node and npm installed. You can check the installation or version by running the following command:
 
-To check installed versions use following commands
-```
-cfn_nag -v
+```bash
 node -v
 npm -v
 ```
 ### AWS CLI SetUp
 
-[Windows:Configure for HTTPS connections to your CodeCommit repositories](https://docs.aws.amazon.com/codecommit/latest/userguide/setting-up-https-windows.html)
-[Linux, macOS, Unix:Configure for HTTPS connections to your CodeCommit repositories](https://docs.aws.amazon.com/codecommit/latest/userguide/setting-up-https-unixes.html)
+- Windows: [Configure for HTTPS connections to your CodeCommit repositories](https://docs.aws.amazon.com/codecommit/latest/userguide/setting-up-https-windows.html)
+- Linux, macOS, Unix: [Configure for HTTPS connections to your CodeCommit repositories](https://docs.aws.amazon.com/codecommit/latest/userguide/setting-up-https-unixes.html)
 
+## Initial Deployment
 
-## Inital deployment in the clean AWS account
-Below you may find instructions for initial deployment in your AWS account
+For the initial deployment in your AWS account, you can run the following command:
 
-1. Clone this repository with following command.
+### Cloning the GitHub Repository
 
-```
+```bash
 git clone --depth 1 https://github.com/aws-samples/aws-codepipeline-cicd.git
+```
+You should remove `.git` dir from the cloned repository as [later](#set-up-remote-codecommit-repository-and-branch) we will use newly created codecommit repository as a remote origin.
+
+```bash
 cd ./aws-codepipeline-cicd
 rm -rf ./.git
 ```
 
-2. Connect to AWS account. It could be temporary security token or landing zone auth. Check that you are in the right account by following command:
+### Connect to AWS Account
+
+It could be temporary security token or landing zone auth. Make sure you are using the correct account and region by running the following command:
 
 ```
 AWS_REGION="eu-west-1"
@@ -88,33 +96,67 @@ echo "${ACCOUNT_NUMBER}"
 ```
 Troubleshooting: Ensure that your IAM user is authorised for all actions (i.e. has permissions as cloudformation execution role, S3 Create Bucket, SSM put parameter, ECR create repository)
 
-3. Prepare the AWS Account by following command
+### Bootstrapping an environment
 
-```
-npm i
+```bash
+npm install
+npm run build
 npm run cdk bootstrap "aws://${ACCOUNT_NUMBER}/${AWS_REGION}"
 ```
-Confirm installation and complete the account preparation
 
-4. Build stacks using following command
+After successful bootstrap, you should see the following output:
+```bash
+ ⏳  Bootstrapping environment aws://{account#}/eu-west-1...
+ ✅  Environment aws://{account#}/eu-west-1 bootstrapped
+```
+
+For more details refer CDK Bootstraping section in [AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html).
+
+### Synthesize a template
+
+To synthesize a CDK app, use the `cdk synth` command:
 
 ```
 npm run cdk synth
 ```
+You should see following output:
 
-You should see following output
 ```
-Successfully synthesized to /Users/user/CodePipeline/cdk.out
+Successfully synthesized to <path-to-directory>/aws-codepipeline-cicd/cdk.out
 Supply a stack id (CodePipeline, Dev-MainStack) to display its template.
 ```
 
-5. Deploy the CodePipeline stack to create repository and pipeline for further execution
+### Deploy CodePipeline stack
+
+Now, you can deploy the CodePipeline stack by running following command. This is required as it will create the necessary prerequisites(CodeCommit Repository) for the CodePipeline.
 
 ```
 npm run cdk -- deploy CodePipeline --require-approval never
 ```
 
-6. After deployment collect the repository name from the pipeline stack and set it as original for your folder.
+You should see output like following:
+```bash
+CodePipeline: deploying...
+CodePipeline: creating CloudFormation changeset...
+
+
+ ✅  CodePipeline
+
+Outputs:
+CodePipeline.RepositoryName = SampleRepository
+Stack ARN:
+arn:aws:cloudformation:REGION:ACCOUNT-ID:stack/CodePipeline/STACK-ID
+```
+
+### Set up remote CodeCommit Repository and branch
+
+After successful deployment of CodePipeline stack, you should see the newly created CodeCommit repository and CodePipeline.
+
+You can see the CodePipeline initial execution in [AWS CodePipeline console](https://eu-west-1.console.aws.amazon.com/codesuite/codepipeline/pipelines). By default when you create a repository in CodeCommit via CDK, no branch is created and thats why CodePipeline is failing to execute with below error:
+
+`The action failed because no branch named main was found in the selected AWS CodeCommit repository SampleRepository. Make sure you are using the correct branch name, and then try again. Error: null`
+
+You can set up remote origin as a `SampleRepository` and create required main branch by running the following command:
 
 ```
 RepoName=$(aws cloudformation describe-stacks --stack-name CodePipeline --query "Stacks[0].Outputs[?OutputKey=='RepositoryName'].OutputValue" --output text)
@@ -129,11 +171,10 @@ git commit -m "Initial commit"
 git push -u origin main
 ```
 
-Open [AWS CodePipeline](https://console.aws.amazon.com/codesuite/codepipeline/pipelines) page and follow the AWS CodePipeline execution.
+## CodePipeline in Action
 
-## Development process via Pipeline
+After successful initial deployment, you should have complete CI/CD pipeline with a `main` branch of `SampleRepository` as a Source branch. As soon as you commit changes to the `main` branch the AWS CodePipeline will trigger and execute following sequence of actions:
 
-After initialisation you have complete CI/CD process with target to the `main` branch. As soon as you commit changes to the main branch the AWS CodePipeline will trigger and execute following sequence of actions:
 1. Get your code from the AWS CodeCommit repository
 2. Build your code
 3. Update the pipeline itself (SelfMutate)

package.json

@@ -25,8 +25,8 @@
     "jest": "^26.4.2",
     "jest-junit": "^13.2.0",
     "ts-jest": "^26.2.0",
-    "ts-node": "^9.0.0",
-    "typescript": "^4.6.2"
+    "ts-node": "^10.8.1",
+    "typescript": "^4.7.3"
   },
   "dependencies": {
     "aws-cdk-lib": "2.22.0",