Skip to content

Latest commit

 

History

History

cdk

README.md

MumbleBee CDK Stack

This is an AWS Cloud Development Kit (CDK) stack that provisions necessary resources to deliver MumbleBee via Amazon S3 + Amazon CloudFront.

Prerequisites

You need the following software installed:

Setting AWS_PROFILE

This document supposes that you have AWS_PROFILE environment variable configured with an AWS profile with sufficient privileges.

Here is my example:

export AWS_PROFILE=codemonger-jp

Setting the toolkit stack name

This document supposes the toolkit stack name is mumble-bee-toolkit-stack and stored in TOOLKIT_STACK_NAME variable. You do not have to follow this convention and may use the default, but I like this because I can avoid mixing up other projects in one place. This is especially useful when you want to clean up a project.

TOOLKIT_STACK_NAME=mumble-bee-toolkit-stack

Setting the toolkit qualifier

This document supposes the toolkit qualifier is mmblbe2023 and stored in BOOTSTRAP_QUALIFIER variable. You should avoid using the default qualifier unless you are using the default toolkit stack name.

BOOTSTRAP_QUALIFIER=mmblbe2023

Preparing configuration file

You have to prepare the following configuration file:

  • configs/domain-name-conf.ts: domain name and certificate ARN for production

The configuration file is never committed to this repository because it contains information specific to your environment. You can find an example at configs/domain-name-conf.example.ts. If you do not have a plan to deploy the application for production, you can copy the example as the configuration file.

Provisioning the certificate for the domain name

How to provision the certificate for the domain name is out of the scope of this document. Here are some references for you:

One important requirement you may easily overlook is that the certificate must be provisioned in the us-east-1 region.

Provisioning the toolkit stack

This is necessary only once before provisioning the CDK stack for the first time.

npx cdk bootstrap --toolkit-stack-name $TOOLKIT_STACK_NAME --qualifier $BOOTSTRAP_QUALIFIER

Synthesizing a CloudFormation template

We can check the CloudFormation template before deploying it.

For development:

npx cdk synth -c "@aws-cdk/core:bootstrapQualifier=$BOOTSTRAP_QUALIFIER"

This CDK stack uses the CDK context variable "mumble-bee:stage" to determine the deployment stage, which is "development" by default. You have to override it for production:

npx cdk synth -c "@aws-cdk/core:bootstrapQualifier=$BOOTSTRAP_QUALIFIER" -c "mumble-bee:stage=production"

Deploying the CDK stack

For development:

npx cdk deploy --toolkit-stack-name $TOOLKIT_STACK_NAME -c "@aws-cdk/core:bootstrapQualifier=$BOOTSTRAP_QUALIFIER"

This CDK stack uses the CDK context variable "mumble-bee:stage" to determine the deployment stage, which is "development" by default. You have to override it for production:

npx cdk deploy --toolkit-stack-name $TOOLKIT_STACK_NAME -c "@aws-cdk/core:bootstrapQualifier=$BOOTSTRAP_QUALIFIER" -c "mumble-bee:stage=production"

The CloudFormation stack will be deployed as:

  • mumble-bee-development for development
  • mumble-bee-production for production

After deployment

The following subsections suppose that the deployment stage is stored in DEPLOYMENT_STAGE variable. Please replace $DEPLOYMENT_STAGE with "development" or "production".

Uploading the application

Please take the following steps to uppload your application to the S3 bucket provisioned by the CDK stack:

  1. Suppose you are in this folder

  2. Build the application for production

    Please refer to Section "Building for production" in /app/README.md for how to do it.

  3. Obtain the S3 bucket name

    The CDK stack outputs the name of the S3 bucket as ContentsBucketName:

    CONTENTS_BUCKET_NAME=`aws cloudformation describe-stacks --stack-name mumble-bee-$DEPLOYMENT_STAGE --query "Stacks[0].Outputs[?OutputKey=='ContentsBucketName']|[0].OutputValue" --output text`

  4. Copy the contents in app's dist folder to the S3 bucket:

    aws s3 cp ../app/dist/ s3://$CONTENTS_BUCKET_NAME/ --recursive

Accessing the uploaded application

The application uploaded to the S3 bucket is delivered via the CloudFront distribution provisioned by this CDK stack. The CDK stack outputs the domain name of the distribution as ContentsDistributionDomainName. You can obtain the domain name with the following command:

aws cloudformation describe-stacks --stack-name mumble-bee-$DEPLOYMENT_STAGE --query "Stacks[0].Outputs[?OutputKey=='ContentsDistributionDomainName']|[0].OutputValue" --output text

You may also assign your own domain name to the distribution for production.