DeepRacer on AWS is a solution that allows you to train and evaluate reinforcement learning models in a three-dimensional simulated autonomous-driving environment. The trained model can then be downloaded to a AWS DeepRacer vehicle (a 1/18th scale RC car capable of running inference on a trained AWS DeepRacer model for autonomous driving) so it can drive in a physical environment. You can also submit your model to a virtual race and have its performance ranked against other models in a virtual leaderboard.
Deploying this solution with the default parameters deploys the following components in your AWS account.
-
A user accesses the DeepRacer on AWS user interface through an Amazon CloudFront distribution, which delivers static web assets from the UI assets bucket and video streams from simulations.
-
The user interface assets are hosted in an Amazon S3 bucket that stores the static web assets comprising the user interface.
-
An Amazon Cognito user pool manages users and user group membership.
-
An Amazon Cognito identity pool manages federation and authorization.
-
AWS IAM user group roles define permissions and levels-of-access for each type of user in the system, used for access control and authorization.
-
AWS Lambda registration hooks execute pre- and post-registration actions including adding new users to the default user group, handling admin profile creation, and more.
-
AWS WAF provides intelligent protection for the API against common attack vectors and allows customers to define custom rules based on individual use cases and usage patterns.
-
Amazon API Gateway routes API requests to their appropriate handler using a defined Smithy model.
-
An AWS DynamoDB table serves as a single table for storing and managing profiles, training jobs, models, evaluation jobs, submissions, and leaderboards.
-
AWS Lambda functions are triggered in response to requests routed from the API and are responsible for CRUD operations, dispatching training/evaluation jobs, and more.
-
A global settings handler AWS Lambda function reads and writes application-level settings to the configuration.
-
AWS AppConfig hosted configuration stores application-level settings, such as usage quotas.
-
AWS Lambda model export functions retrieve the asset URL and package assets for use in exporting models from the system.
-
An Amazon SQS dead-letter queue catches failed export jobs thrown from the asset packaging function.
-
A virtual model bucket (Amazon S3) stores exported models and provides access to them via pre-signed URL.
-
A model import AWS Lambda function receives requests to import a model onto the system and creates a new import job.
-
Amazon SQS model import queues (queue and DLQ) receive jobs from the model import function and hold them until they are accepted by the dispatcher.
-
A failed request handler AWS Lambda function handles failed requests and updates their status to reflect their current state.
-
An import dispatcher AWS Lambda function takes a job from the queue and dispatches it to the workflow.
-
A reward function validator AWS Lambda function checks the reward function and validates/sanitizes the customer-provided code before it is saved to the system.
-
An import model validator AWS Lambda function checks and validates the imported model before it is saved to the system.
-
An import model assets AWS Lambda function brings in model assets from the upload bucket.
-
An import completion handler AWS Lambda function handles status updates when a job is completed successfully.
-
An upload bucket (Amazon S3) stores uploaded (but not yet imported) assets from the user.
-
An Amazon SQS FIFO queue receives requests for training and evaluation jobs and stores them in FIFO order.
-
A job dispatcher AWS Lambda function picks a job off the top of the FIFO queue and dispatches it to the workflow.
-
AWS Lambda workflow functions handle setting up the job, setting status, and other workflow tasks.
-
Amazon SageMaker performs the actual training and evaluation of the model using the reward function and hyperparameters provided.
-
Amazon Kinesis Video Streams handles presenting the simulation video to the user from the SageMaker training job.
-
A user data bucket (Amazon S3) stores all user data including trained models, evaluation results, and other assets generated during the DeepRacer workflow.
-
An Amazon DynamoDB Stream captures item-level changes from the main table and delivers them to downstream Lambda consumers, enabling event-driven orchestration of live race evaluations and real-time broadcast of race state to spectators.
-
A AWS Lambda Broadcast Handler (LiveBroadcastHandler) is triggered by the DynamoDB stream and detects relevant state changes — such as evaluation started/completed, leaderboard updates, and winner declarations — and publishes corresponding events to the IoT Core MQTT topic for the active race, delivering real-time updates to connected spectator browsers.
-
AWS IoT Core provides a managed WebSocket pub/sub channel for delivering live race state updates to spectator and participant browsers. Each live race uses a dedicated MQTT topic scoped by leaderboard ID. Spectators subscribe via WebSocket; the Broadcast Handler publishes via IAM-authorized HTTPS. IoT Core handles connection management, fan-out, and scaling without requiring a connections table or custom connect/disconnect handlers.
-
AWS EventBridge Schedules triggers the SafetyNet Lambda whenever a live race Step Functions execution reaches a terminal state (succeeded, failed, aborted, or timed out), ensuring the execution lock is cleared and pending evaluations are retriggered without manual intervention.
-
AWS Lambda Queue API Handlers are a set of Lambda functions that back the live race queue management endpoints. They handle facilitator operations including listing the queue, reordering submissions via fractional indexing, removing submissions, resetting in-progress or failed models, clearing the leaderboard, launching the live race, and declaring a winner.
-
An AWS Lambda Attach IoT Policy function grants newly authenticated users the IoT Core policy required to subscribe to live race MQTT topics over WebSocket, enabling real-time race state delivery to their browser sessions.
-
A AWS Lambda Stream Handler is triggered by the DynamoDB stream and is responsible for auto-starting a new Step Functions execution for a live race when one or more submissions with PENDING status exist in the queue, the race is IN_PROGRESS, autolaunch is enabled, and no execution is currently running. It acquires the execution lock via a conditional write before starting the execution.
-
A AWS Lambda SafetyNet function is invoked by EventBridge when a live race Step Functions execution reaches any terminal state. It clears the execution lock with a conditional write, applies a backoff check if the execution has failed repeatedly, and touches a PENDING queue item to generate a DynamoDB stream event — retriggering the Stream Handler to start a new execution if items remain in the queue.
- The source code for the DeepRacer on AWS is located in
./source.
DeepRacer on AWS is structured as monorepo. See below for package layouts and intended contents.
┣ 📦 deployment
┃ ┗ 📂cdk-solution-helper Lightweight helper that cleans-up synthesized templates from the CDK
┗ 📦 source
┣ 📂apps Applications - Code not imported/consumed outside of its own package
┃ ┣ 📂infra CDK application
┃ ┃ ┣ 📂bin
┃ ┃ ┃ ┗ 📜deepRacerIndy.ts Main CDK app definition
┃ ┃ ┗ 📂lib
┃ ┃ ┣ 📂constructs CDK constructs
┃ ┃ ┗ 📂stacks CDK stacks
┃ ┗ 📂website Website application
┃ ┗ 📂src
┃ ┣ 📂assets Static assets (ie. images)
┃ ┣ 📂components React components re-used throughout the website
┃ ┣ 📂pages React components for individual website pages
┃ ┗ 📂utils Utils specific to the website application
┗ 📂libs Libraries - Code consumed/imported by apps or other libraries
┣ 📂config Config package - App-wide configuration
┃ ┗ 📂src
┃ ┣ 📂configs Domain specific configurations
┃ ┣ 📂defaults Config default values
┃ ┗ 📂types Config definitions
┣ 📂database Database package - Database related implementation
┃ ┗ 📂src
┃ ┣ 📂constants Database constants
┃ ┣ 📂dao DAO implementations
┃ ┣ 📂entities ElectroDB entities
┃ ┗ 📂utils Database specific utils
┣ 📂lambda Lambda Package - lambda handlers
┃ ┗ 📂src
┃ ┣ 📂api API lambda code
┃ ┃ ┣ 📂handlers API lambda handler implementations
┃ ┃ ┣ 📂types API TypeScript types
┃ ┃ ┗ 📂utils API lambda utils
┃ ┣ 📂cognito Cognito lambda code
┃ ┗ 📂workflow Workflow lambda code
┣ 📂model Model package - API Smithy model
┃ ┗ 📂src
┃ ┗ 📂main
┃ ┗ 📂smithy
┃ ┣ 📂operations Smithy definitions for API operations
┃ ┣ 📂types Smithy definitions for API types
┃ ┗ 📜main.smithy Smithy API definition
┣ 📂typescript-client Auto-generated from model - API TypeScript client for website to consume
┣ 📂typescript-server-client Auto-generated from model - API TypeScript client for API lambdas to consume
┗ 📂utils Utils package - App-wide utils
You can launch this solution with one click from the solution home page:
Please ensure you test the templates before updating any production deployments.
To customize the solution, follow the steps below:
- AWS Command Line Interface
- Java 17
- Node v20+
- pnpm package manager
Follow the instructions for your platform here.
It is recommended to manage node installations with a node version manager, such as nvm.
Run the nvm install script:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
Install Node v22 using nvm:
nvm install 22
Select Node v22 as the version to use:
nvm use 22
Confirm that Node v22 is being used:
node --version
pnpm is a javascript package manager that is faster and more efficient than npm.
Since v16.13, Node.js is shipping Corepack for managing package managers. This is an experimental feature, so you need to enable it by running:
corepack enable pnpm
Nx can be installed globally to remove the need to prefix nx commands with "pnpm" by running:
pnpm i -g nx
If you go this route, you can remove "pnpm" from any commands that run nx.
For example:
pnpm nx test database
becomes
nx test database
git clone https://github.com/aws-solutions/deepracer-on-aws
Install package dependencies by running the following from the monorepo root (source folder):
pnpm install
This will install package.json dependencies for all apps and libs in the monorepo, as well as shared dev dependencies from package.json in the monorepo root.
After introducing changes, run the unit tests to make sure the customizations don't break existing functionality
cd ./deployment
chmod +x ./run-unit-tests.sh
./run-unit-tests.sh
Define the following environment variables in your console session:
REGIONAL_ARTIFACT_BUCKET=my-bucket-name # S3 bucket name prefix where customized regional code will reside
GLOBAL_ARTIFACT_BUCKET=my-bucket-name # S3 bucket name where customized global code will reside
SOLUTION_NAME=my-solution-name # customized solution name
VERSION=my-version # version number for the customized code
In order to compile the solution, the build-s3 will install the AWS CDK.
cd ./deployment
chmod +x ./build-s3-dist.sh
./build-s3-dist.sh $REGIONAL_ARTIFACT_BUCKET $SOLUTION_NAME $VERSION $GLOBAL_ARTIFACT_BUCKET
When creating the bucket for solution artifacts it is recommended to
- Use randomized names as part of your bucket naming strategy.
- Ensure buckets are not public.
- Verify bucket ownership prior to uploading templates or code artifacts.
Note: The created bucket for regional artifacts must include the region in the bucket name (for example, mybucket-name-us-east-1).
aws s3 sync ./global-s3-assets s3://$GLOBAL_ARTIFACT_BUCKET/$SOLUTION_NAME/$VERSION --acl bucket-owner-full-control
aws s3 sync ./regional-s3-assets s3://$REGIONAL_ARTIFACT_BUCKET-us-east-1/$SOLUTION_NAME/$VERSION --acl bucket-owner-full-control
- Get the link of the template uploaded to your Amazon S3 bucket (created as $REGIONAL_ARTIFACT_BUCKET in the previous step)
- Deploy the solution to your account by launching a new AWS CloudFormation stack
- Provide a valid email address as the value for the ADMIN_EMAIL environment variable. This will be used to set up the initial admin profile.
export ADMIN_EMAIL='user@example.com'
- If you are deploying more than one instance of DeepRacer on AWS into the same account, provide a unique value for the NAMESPACE environment variable. This will help with labeling and separating the resources created by each deployment. It must use lowercase alphanumeric characters with a minimum length of 3 and a maximum length of 12.
export NAMESPACE='deepracer1'
- Choose which delivery method to use for sending authentication emails. DeepRacer on AWS supports both Amazon Cognito and Amazon SES as delivery methods. Amazon Cognito is the default delivery method and requires no prior service approval, but is better suited for low volume use cases due to its limit of 50 emails per day per account. Amazon SES is also supported for higher sending limits and custom sender addresses, but requires a verified email address and production status.
To use SES as the delivery method for authentication emails, follow the instructions in the Prerequisites section of the implementation guide on how to set up a verified sender email address and request production status. Then:
export EMAIL_DELIVERY_METHOD='SES'
export SES_VERIFIED_EMAIL='noreply@example.com'
- If you want to use a public image for the reward validation function (or private image with appropriate permissions)
export PUBLIC_ECR_REGISTRY=${AWS_ACCOUNT}.dkr.ecr.${AWS_REGION}.amazonaws.com
The solution uses CDK context values for container image configuration. These are defined in source/apps/infra/cdk.json and can be overridden during deployment:
Default context values:
PUBLIC_ECR_REGISTRY: "public.ecr.aws/aws-solutions"MODEL_VALIDATION_REPO_NAME: "deepracer-on-aws-model-validation"REWARD_VALIDATION_REPO_NAME: "deepracer-on-aws-reward-function-validation"SIMAPP_REPO_NAME: "deepracer-on-aws-simapp"
Override context values during deployment:
pnpm nx deploy infra --context PUBLIC_ECR_REGISTRY=my-registry.com --context PUBLIC_ECR_REGISTRY=<PRIVATE_ECR_REPO>
If this is your first time using CDK in your AWS account and region, you need to bootstrap it:
cdk bootstrap aws://<account-id>/<region>
This creates the necessary resources for CDK deployments in your account.
Run the build command from the source directory
pnpm build
Deploy the infrastructure by running the following from the monorepo root (source folder).
pnpm nx deploy infra
This solution sends operational metrics to AWS (the “Data”) about the use of this solution. We use this Data to better understand how customers use this solution and related services and products. AWS’s collection of this Data is subject to the AWS Privacy Notice.
Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.