Skip to content

Latest commit

 

History

History
266 lines (178 loc) · 10.2 KB

README.md

File metadata and controls

266 lines (178 loc) · 10.2 KB

Mumble CDK Stack

Defines an AWS Cloud Development Kit (CDK) stack that provisions AWS resources for the Mumble service.

This document desribes how to deploy and configure the CDK stack. /docs/architecture.md provides an overview of the Mumble service architecture.

Prerequisites

You need the following software installed:

Resolving dependencies

npm ci

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-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-toolkit-stack

Setting the toolkit qualifier

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

BOOTSTRAP_QUALIFIER=mumble2023

Preparing configuration files

You have to prepare the following configuration files:

These files are never committed to this repository because they contain information specific to your environment.

configs/cognito-config.ts

You can find an example at configs/cognito-config.example.ts. If your callback URLs are not determined yet, you can use a copy of the example and edit them later on AWS console.

cp configs/cognito-config.example.ts configs/cognito-config.ts

You have to specify a unique domain prefix.

configs/domain-name-config.ts

You can find an example at configs/domain-name-config.example.ts. If you do not plan to deploy for production, you can use a copy of the example:

cp configs/domain-name-config.example.ts configs/domain-name-config.ts

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: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: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: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:stage=production"

The CloudFormation stack will be deployed as:

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

After deployment

The following subsections suppose you have the deployment stage stored in $DEPLOYMENT_STAGE variable. Please replace $DEPLOYMENT_STAGE with a proper deployment stage: "development" or "production".

Setting the domain name parameter

You have to set the parameter that store the domain name of the Mumble endpoints in Parameter Store on AWS Systems Manager. The path of the parameter is available as the CloudFormation output DomainNameParameterPath.

You can use the npm script setup-domain-name to configure it.

For development:

npm run setup-domain-name -- development

For production:

npm run setup-domain-name -- production $YOUR_DOMAIN_NAME

Please replace $YOUR_DOMAIN_NAME with your domain name; e.g., mumble.codemonger.io.

Cognito parameters for a Web client

A Web client of the Mumble API will need the following parameters to authenticate users:

These are included in the CloudFormation outputs. Please refer to Section "Outputs from the CDK stack" for how to obtain them or follow the above links.

Configuring Cognito user pool client callback URLs

You can configure the callback URLs with the configuration file (configs/cognito-config.ts), though, you can also do it on AWS console after deploying the CDK stack. Here are some references for you:

Creating a new Mumble user

To create a new Mumble user, you have to take the following steps:

  • create a new Cognito user
  • generate an RSA key pair for the new user
  • save the private key in Parameter Store on AWS Systems Manager
  • create an item in the user table for the new user

You can use the npm script create-user to do the above jobs to create a new user.

npm run create-user -- \
    username \
    email \
    --name "Full Name" \
    --summary "About the user" \
    --url "https://example.com"

You have to add --stage production option for production:

npm run create-user -- \
    username \
    email \
    --name "Full Name" \
    --summary "About the user" \
    --url "https://example.com" \
    --stage production

Outputs from the CDK stack

The following subsections show the CDK stack outputs and how to obtain them. Please replace $DEPLOYMENT_STAGE with a proper deployment stage: "development" or "production".

Cognito user pool ID

UserPoolId contains the Cognito user pool ID.

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

Cognito user pool client ID

UserPoolHostedUiClientId contains the Cognito user pool client ID.

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

Cognito user pool domain name

UserPoolDomainName contains the domain name of the Cognito user pool.

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

Identity pool ID

IdentityPoolId contains the Cognito identity pool ID.

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

Parameter path for the domain name

DomainNameParameterPath contains the parameter path in Parameter Store on AWS Systems Manager, which stores the domain name of the Mumble API.

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

Domain name of the Mumble endpoints

MumbleApiDistributionDomainName contains the domain name of the CloudFront distribution for the Mumble API.

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

Name of the S3 bucket for objects

ObjectsBucketName contains the name of the S3 bucket for objects.

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