johngreen-dev / websocket-chat-application

This application provides the CDK project and a frontend that allows you to build a serverless chat application based on API Gateway's WebSocket-based API feature.

Serverless chat application using ApiGateway Websockets

This project lets you provision a ready-to-use fully serverless real-time chat application using Amazon ApiGateway Websockets. The infrastructure code is using the AWS Cloud Development Kit(AWS CDK). The frontend is written using Angular 12.

Features

• "One-click" serverless deployment using AWS CDK
• Infrastructure is split into 6 interdependent stacks (Authorization, Database, REST API, Websocket API, Frontend, Observability)
• Secure HTTPS connection and content delivery using Amazon Cloudfront
• Built-in authentication using Amazon Cognito
• Built-in REST API authorization using Cognito UserPool Authorizer
• Synchronous real-time messaging using API Gateway Websocket API
• Asynchronous user status updates using Amazon SQS and API Gateway Websocket API
• Environment-agnostic Single Page Application frontend (dynamic environment configuration loading)
• Complete request tracing using AWS X-Ray
• Lambda Powertools integration (beta)
• Structured logging and monitoring using Amazon Cloudwatch
• Custom metrics & Cloudwatch dashboard
• Built-in infrastructure security check using CDK-NAG

Solution Overview

Project structure

├── infrastructure                      # Infrastructure code via CDK(Typescript).
│   ├── bin                             # CDK App - Deploys the stacks  
│   ├── lib                             #
|   |   ├── auth-stack.ts               # Contains the Cognito Userpool
|   |   ├── database-stack.ts           # DynamoDB table definitions
|   |   ├── frontend-stack.ts           # Cloudfront distribution, S3 bucket for static hosting and additional resources
|   |   ├── rest-api-stack.ts           # ApiGateway REST API to support the frontend application
|   |   ├── websocket-stack.ts          # ApiGateway Websocket API for real-time communication
|   |   ├── observability-stack.ts      # CloudWatch Dashboard with custom metrics
├── UI                                  # Angular 12 Single Page Application (SPA)
└── ...

The cdk.json file inside infrastructure directory tells the CDK Toolkit how to execute your app.

Prerequisites

• AWS CLI installed and configured with the aws account you want to use.
• AWS CDK installed and configured with the aws account you want to use.
• docker installed and is up and running locally (required for the lambda function builds).
• Angular CLI installed.

Security considerations

For the sake of this demo, not all security features are enabled to save cost and effort of setting up a working PoC.

Below you can find a list of security recommendations in case you would like to deploy the infrastructure in a production environment:

• Currently all registered users can immediately access the application without second factor authentication or account confirmation. This is not suitable for production use. Please change the Cognito configuration to enable e-mail/sms verification and MFA. In a future release this will be addressed with a feature flag to toggle between different authentication modes.
• The DynamoDB tables have no backups configured by default. Please enable PITR (point-in-time recovery) and table backups. The tables will be removed on cloudformation stack deletion.
• Logging for the APIGateway API/stage and for the Cloudfront distribution are disabled. Please enable these additional logs in production environments for audit and troubleshooting purposes.
• The Cloudfront distribution uses the default cloudfront domain and viewer certificate. The default viewer certificate defaults to the TLSv1 protocol. In order to enforce newer protocols, please use a custom domain with a custom certificate and set the MinimumProtocolVersion to TLSv1.2.

Getting started

Deployment

• Change directory to where infrastructure code lives.

    cd infrastructure

• Restore NPM packages for the project

    npm install

• Bootstrap your AWS account as it's required for the automated Docker image build and deployment

    cdk bootstrap aws://{ACCOUNT_ID}/{REGION}

• Synthesize the cdk stack to emits the synthesized CloudFormation template. Set up will make sure to build and package the lambda functions residing in the handlers directory.

    cdk synth

• Deploy the CDK application

    cdk deploy --all

[Optional] - Building the frontend

• Change directory to where UI code lives.

    cd UI

• Restore NPM packages for the project

    npm install

• Build the frontend application

    ng build --prod

Opening the chat application

The chat application's URL will be found at the Frontend stack's output. Open the Cloudfront Distribution's URL in your browser, where you'll be redirected to the Cognito login/singup page.

Cleanup

Run the following command to delete the infrastructure stacks:

    cdk destroy --all

Observability

The backend is fully instrumented using AWS Xray and Lambda Powertools for TypeScript (beta).

Custom Metrics & Cloudwatch Dashboard

The backend outputs 3 custom metrics from the websocket API backend:

• New Connections
• Closed Connections
• Messages Delivered

The Observability Stack creates a custom Cloudwatch Dashboard where these metrics are visualised.

AWS X-Ray and ServiceMap integration

Requests are automatically traced and instrumented using AWS X-Ray. You can use the ServiceMap to visualise the interactions between the backend components and trace latencies, response codes, etc. between these components.

API Handler documentation

You can find a more detailed description of what the API handler functions are doing here.

Found an issue? Anything to add?

See CONTRIBUTING for more information.

License

This library is licensed under the MIT-0 License. See the LICENSE file.