Skip to content

Home

Jump to bottom
Anjan Biswas edited this page Jan 12, 2023 · 3 revisions

Getting Started

You can deploy this demo from either your local machine or using a cloud IDE such as AWS Cloud9. In order to ensure a clean and error free deployment experience, we highly recommend using AWS Cloud9 to deploy the project into an AWS account. AWS Cloud9 environment comes pre-configured with all the development tools required to deploy this project so that you can quickly get started.

If you would prefer to deploy this from your local machine, please ensure the following dependencies are installed before proceeding.

Dependency Description Version Installation
node npm NodeJS and Node Package Manager latest (minimum npm v7 & node v14) install
Docker Docker Desktop is an application for MacOS and Windows machines for the building and sharing of containerized applications and microservices. latest install
AWS CDK Toolkit The AWS CDK (Cloud Development Kit) Toolkit is a cli (command line interface) that is used to develop, build, and deploy CDK applications. latest install
AWS CLI The AWS command line interface latest install

Setup AWS Cloud9 environment

Search for "Cloud9" from the top search bar of the AWS console, click on "Cloud9". Once in the Cloud9 console follow the steps-

  1. On the Cloud9 console page click "Create environment" button.

step-2

  1. In the next screen, enter an environment name and an (optional) description. Click "Next step"

step-2

  1. In the "Configure settings" screen, change the "Instance type" to m5.large, leave everything as default and click "Next step"

step-3

  1. Review your selected values in the "Review" screen and click "Create environment"

  2. You will be navigated to the Coud9 IDE. Wait for the deployment to complete.

step-5

Accessing the AWS Cloud9 Environment

Search for "Cloud9" on the top search bar of the AWS Console. Click on "Cloud9", you will be navigated to the AWS Cloud9 console where you will see the Cloud9 environment. Select the environment, and click "Open IDE". You will be taken to the cloud IDE.

cfn-step-2

Verify dependencies (optional)

Verify that you have all the dependencies required in the Cloud9 environment required to build and deploy the project. At the terminal found in the bottom of the IDE type the following commands. If you do not see a terminal, open a new terminal by clicking the "+" button next to a tab then clicking "New Terminal".

c9-terminal

Check node version

node -v

Check npm version

npm -v

Check docker version

docker --version

Check AWS CDK version

cdk --version

Check the AWS CLI version

aws --version

Clone the project

While in the terminal window, clone this project repository using the command below by replacing the <repo_url> with the URL of this repository.

git clone <repo_url> idp-poc-demo

Once the repo clone is complete, you should now see a new directory idp-poc-demo in the left navigation pane of the Cloud9 IDE.

Troubleshooting

Although, the single-command deployment is expected to handle the build and deployment for you and fail gracefully, but as we all know, things can (and will) break in real world. So here are some common causes of failures and how to troubleshoot them.

Deployment failed due insufficient space in Cloud9 environment

If you are using AWS Cloud9 environment to deploy the project, you may run into insufficient space. The build process in the project creates Docker images that can grow large in size. With a Cloud9 instance the default storage assigned is usually 10Gb, which at times can be insufficient for deployment purposes of medium to large projects. If you encounter space issues, you can refer to this document to quickly execute a script to resize the disk of your Cloud9 environment.

Once you have resized, you can retry the installation steps. If you continue to encounter Stack related issues, you may need to delete the CloudFormation stacks manually and retry the installation. The following step discusses manual stack deletion.

Reverting from a deployment failure

You may have to delete the stacks if your deployment fails unexpectedly in the middle of the deployment. The CDK application in this project deploys a number of different stacks, so it is possible for a few stacks get deployed correctly, while others fail. In such cases, the best course of action is to delete all the stacks manually from Amazon CloudFormation console. It is safe to delete these CloudFormation stacks manually in the following order-

  • IDPDeidWebDeployStack (this will delete a nested stack within it)
  • IDPDeidBackendStack
  • IdpCdkDeidAppStack
  • IDPDeidLambdaStack
  • IDPDeidStepFunctionStack

To delete CloudFormation stacks, navigate to the AWS CloudFormation console, select the stack name and click "Delete" button at the top. Delete one stack at a time.

Stack deletion failures

Once you are done with your project, you may want to delete the CloudFormation stacks using the cleanup steps. One of the common reasons for the stack deletion to fail is non-empty Amazon S3 buckets. If you have successfully deployed the project before, and have been using it, chances are that you have documents and files in the IDP S3 bucket that was created as part of the project. The CDK app is created in a way that removal of the stack will also remove the contents of the bucket before deleting the bucket automatically. However, in some cases there may be situations where files may still be present in the bucket because you have enabled versioning on it (either manually after the bucket was created, or by modifying the stack before deployment). In such cases, you must delete all the object versions within the bucket manually before proceeding to delete the Stack itself.

NOTE: Please make sure to backup all your data from the IDP S3 bucket before deleting the objects.

Reverting all changes

At times, you may want to start a fresh install by deleting all the partially deployed stacks. You can follow the instructions above to delete the application stacks in CloudFormation. However, the AWS CDK Bootstrap process also creates resources that you may want to delete. To delete resources created by the bootstrap process, you can delete the stack named CDKToolkit from CloudFormation manually. Subsequently, can you also delete the CDK bootstrap S3 bucket which will have a naming convention of cdk-xxxxxxxx-assets-<account_id>-<region>.

Note that the CDKToolkit stack deletion may fail if the cdk-xxxxxxxx-assets-<account_id>-<region> is not empty. If that happens, delete the contents of the bucket manually and retry the stack deletion. Finally, delete the bucket manually.

NOTE: It is safe to delete the CDK Bootstrap resources. The installation process will attempt to bootstrap and create all the necessary resources again.

I've customized the stack, and now I am encountering circular stack references error

Circular dependencies happen when Stack A depends on Stack B, which in turn depends on Stack A, causing the circular reference. It may not be immediately obvious of such dependencies when developing. Refer to Handling circular dependency errors in AWS CloudFormation for more information. You can also refer to this CDK GitHub document for tips and tricks on handling cross stack dependencies with CDK.

Clone this wiki locally