A serverless demo intended as an educational tool to demonstrate how you can build an application that enables real-time social UGC (User Generated Content) use cases using Amazon IVS Stages and Amazon IVS Chat. This README includes instructions for deploying the Amazon IVS Real-time Serverless demo to an AWS Account.
IMPORTANT NOTE: Deploying this demo application in your AWS account will create and consume AWS resources, which will cost money.
- AWS CLI Version 2
- NodeJS and
npm(npm is usually installed with NodeJS)- If you have node version manager installed, run
nvm useto sync your node version with this project
- If you have node version manager installed, run
- Access to an AWS Account with at least the following permissions:
- Create IAM Roles
- Create Lambda Functions
- Create Secret Manager Secrets
- Create Amazon IVS Stages and Chat Rooms
- Create Amazon DynamoDB Tables
- Create EventBridge Rules
- Create Step Functions State Machines
For configuration specifics, refer to the AWS CLI User Guide.
-
Click the Launch stack button that corresponds to the region that is geographically closest to you
North America us-east-1 (N. Virginia) us-west-2 (Oregon) Europe eu-west-1 (Ireland) eu-central-1 (Frankfurt) Asia Pacific ap-south-1 (Mumbai) ap-northeast-1 (Tokyo) ap-northeast-2 (Seoul) -
Follow the steps on the Create stack page. You may optionally specify a different Stack name.
-
After completing all steps, select Submit to launch and deploy the stack.
When the deployment successfully completes, save the following values in the Outputs tab to generate your Authentication code. You will need to enter this code when prompted by the mobile apps:
domainName(the first part of this is yourdomainId)secretUrl(used to retrieve yourapiKey)
Open the secretUrl in your web browser and click the Retrieve secret value button in the Secret value section. Once the secrets are visible, copy the apiKey value.
To generate your Authentication code, join the domainId and apiKey with a dash: ${domainId}-${apiKey}.
For example, if your domainName is
d0abcdefghijk.cloudfront.netand apiKey isAbCDEFgHIJKLmnOPQrsTUV, your authentication code isd0abcdefghijk-AbCDEFgHIJKLmnOPQrsTUV.
On your mobile device, simply enter this value when prompted by the app.
-
If this is your first time deploying the backend stack, run the following command:
make app STACK=YOUR_STACK_NAME (default: IVSRealTimeDemo)Otherwise, run the following command to skip the
installandbootstrapprocesses and go straight into deploying:make deploy STACK=YOUR_STACK_NAME (default: IVSRealTimeDemo)See Commands for a comprehensive list of the
appanddeployoptions. -
Press
ywhen prompted to acknowledge and proceed with the deployment
When the deployment successfully completes, copy the ⭐️ Domain ID and 🔑 API key values outputted in your terminal session. On your mobile device, simply enter these values when prompted by the app.
Alternatively, you may use the mobile app to scan the 🔎 Authentication QR code. Doing so will automatically paste the customer ID and API key into the app and sign you in immediately.
To delete a deployed backend stack, run the following command:
make destroy STACK=YOUR_STACK_NAME
See Commands for a comprehensive list of the destroy option.
Note: resources created after the deployment will not be deleted. Such resources may include Stages and Chat Rooms.
When deploying the stack using the command-line, a CloudWatch alarm will be triggered when the API returns 5 or more server errors (5XX) within 10 minutes. To receive email notifications when an alarm is triggered, you must pass an ALARMS_EMAIL option to the make app or make deploy commands. For example,
make deploy ALARMS_EMAIL=youremail@example.com
Once the stack has been deployed, you will receive an email from AWS prompting you to confirm the SNS topic subscription to receive email notifications.
| Description | Options | |
|---|---|---|
| app | Installs NPM dependencies, bootstraps, and deploys the stack | AWS_PROFILE, AWS_REGION, STACK, NAG |
| install | Installs NPM dependencies | - |
| bootstrap | Deploys the CDK Toolkit staging stack | AWS_PROFILE, AWS_REGION, STACK, NAG |
| synth | Synthesizes the CDK app and produces a cloud assembly in cdk.out | AWS_PROFILE, AWS_REGION, STACK, NAG |
| deploy | Deploys the stack | AWS_PROFILE, AWS_REGION, STACK, NAG, ALARMS_EMAIL, TERM_PROTECTION |
| output | Retrieves the CloudFormation stack outputs | STACK |
| destroy | Destroys the stack and cleans up | AWS_PROFILE, AWS_REGION, STACK, NAG |
| clean | Deletes the cloud assembly directory (cdk.out) | - |
| seed | Creates a specified number of randomly generated demo items | AWS_PROFILE, AWS_REGION, STACK, COUNT, TYPE |
| delete-seed | Deletes all seeded items | AWS_PROFILE, AWS_REGION, STACK |
| publish | Publishes stack file assets to an S3 bucket and generate a launch stack URL | AWS_PROFILE, AWS_REGION, STACK, NAG, FILE_ASSETS_BUCKET_NAME_PREFIX |
| help | Shows a help message with all the available make rules | - |
AWS_PROFILE - named AWS CLI profile used for commands that interact with AWS. Defaults to default.
AWS_REGION - the AWS region used for commands that interact with AWS. Defaults to the region associated with your default AWS CLI profile.
STACK - the stack name. Defaults to IVSRealTimeDemo.
ALARMS_EMAIL - the email that will be receiving CloudWatch alarm notifications.
TERM_PROTECTION - set to true to enable stack termination protection. Defaults to false.
NAG - set to true to enable application security and compliance checks. Defaults to false.
COUNT - the number of demo items to seed (maximum is 10). Defaults to 1.
TYPE - the type of demo items to seed (either video or audio). Defaults to video.
FILE_ASSETS_BUCKET_NAME_PREFIX - the name prefix used to create or retrieve the S3 bucket to which file assets are saved from the publish command. This prefix is prepended with the AWS region to create the complete bucket name. Required when running the publish command.