Creating an interactive serverless application using WebSocket

In this tutorial, you will deploy an online game based on Node.js using WebSocket.

Your game's static resources will be stored in an Object Storage bucket and its data, in Managed Service for YDB databases. You will use Data Streams to transfer the game data and Cloud Functions to process it. Message Queue will handle communication between the application components. Yandex Lockbox will securely deliver secrets to your app. An API Gateway will accept user requests and redirect them to Cloud Functions.

The game uses Telegram integration to authorize users.

To create an online game:

1. Set up your environment.
2. Create Yandex Managed Service for YDB databases.
3. Create a stream in Yandex Data Streams.
4. Create a Yandex Lockbox secret.
5. Deploy your project.
6. Create access keys for the service accounts.
7. Create a new secret version and deploy your project again.
8. Create a Yandex API Gateway.
9. Add your domain to the Telegram bot.
10. Test your application.

If you no longer need the resources you created, delete them.

Getting startedGetting started

Sign up for Yandex Cloud and create a billing account:

1. Navigate to the management console and log in to Yandex Cloud or create a new account.
2. On the Yandex Cloud Billing page, make sure you have a billing account linked and it has the ACTIVE or TRIAL_ACTIVE status. If you do not have a billing account, create one and link a cloud to it.

If you have an active billing account, you can navigate to the cloud page to create or select a folder for your infrastructure.

Learn more about clouds and folders here.

Required paid resourcesRequired paid resources

The infrastructure support cost for this tutorial includes:

• Fee for data operations and the amount of stored data (see Yandex Managed Service for YDB pricing).
• Fee for using a data stream (see Yandex Data Streams pricing).
• Fee for secret storage (see Yandex Lockbox pricing).
• Fee for data storage and data operations (see Yandex Object Storage pricing).
• Fee for requests to API gateways you create and outbound traffic (see Yandex API Gateway pricing).
• Fee for queue requests and outbound traffic (see Yandex Message Queue pricing).
• Fee for function invocations and computing resources allocated to run the functions (see Yandex Cloud Functions pricing).

Set up your environmentSet up your environment

Download the projectDownload the project

Clone the yc-serverless-game repository:

git clone https://github.com/yandex-cloud-examples/yc-serverless-game.git

Create a Telegram botCreate a Telegram bot

Create a bot in Telegram and get a token.

1. To create a new bot, start BotFather and run this command:

   /newbot
   

2. In the name field, enter a name for the bot, e.g., Serverless Game With WebSockets. This is the name users will see when chatting with the bot.

3. In the username field, enter a username for the bot, e.g., ServerlessGameWithWebSocketsBot. You can use it to find the bot in Telegram. The username must end with ...Bot or ..._bot.

4. You will get the t.me/ServerlessGameWithWebSocketsBot address and token in response.

5. Save the username to the TG_BOT_LOGIN variable:

   echo "export TG_BOT_LOGIN=<bot_username>" >> ~/.bashrc && . ~/.bashrc
   echo $TG_BOT_LOGIN
   

6. Save the token to the TG_BOT_TOKEN variable:

   echo "export TG_BOT_TOKEN=<token>" >> ~/.bashrc && . ~/.bashrc
   echo $TG_BOT_TOKEN
   

Get an access tokenGet an access token

echo "export YC_IAM_TOKEN=$(yc iam create-token)" >> ~/.bashrc && . ~/.bashrc
echo $YC_IAM_TOKEN

echo "export OAUTH_TOKEN=$(yc config get token)" >> ~/.bashrc && . ~/.bashrc
echo $OAUTH_TOKEN

Create a service accountCreate a service account

1. Create a service account named sls-deploy and save its name to the SERVICE_ACCOUNT_GAME variable:

   export SERVICE_ACCOUNT_GAME=$(yc iam service-account create --name sls-deploy \
     --description "service account for serverless game" \
     --format json | jq -r .)
   
   echo $SERVICE_ACCOUNT_GAME
   

2. The id line in the command output will show the service account ID. Save it to the SERVICE_ACCOUNT_GAME_ID variable:

   echo "export SERVICE_ACCOUNT_GAME_ID=<service_account_ID>" >> ~/.bashrc && . ~/.bashrc
   

3. Assign the editor role to the service account:

   echo "export YC_FOLDER_ID=$(yc config get folder-id)" >> ~/.bashrc && . ~/.bashrc
   echo $YC_FOLDER_ID
   
   echo "export YC_CLOUD_ID=$(yc config get cloud-id)" >> ~/.bashrc && . ~/.bashrc
   echo $YC_CLOUD_ID
   
   yc resource-manager folder add-access-binding $YC_FOLDER_ID \
   --subject serviceAccount:$SERVICE_ACCOUNT_GAME_ID \
   --role editor
   

4. Create an authorized key for the service account:

   yc iam key create \
     --service-account-name sls-deploy \
     --output sls-deploy.sa
   
   echo "export SA_KEY_FILE=$PWD/sls-deploy.sa" >> ~/.bashrc && . ~/.bashrc
   echo $SA_KEY_FILE
   

5. Create a static access key for the service account:

   yc iam access-key create --service-account-id $SERVICE_ACCOUNT_GAME_ID
   

   Result:

   access_key:
       id: ajeibet3219********
       service_account_id: ajehr1tv2eo1********
       created_at: "2023-03-13T10:20:58.471421425Z"
       key_id: YCAS33CT2mPCVFh3K********
   secret: YCNhBcdvfDdssIuBa-FDl6zZz0MSky********
   

6. Save the key_id value to the AWS_ACCESS_KEY_ID variable and the secret value to the AWS_SECRET_ACCESS_KEY variable:

   echo "export AWS_ACCESS_KEY_ID=<key_ID>" >> ~/.bashrc && . ~/.bashrc
   echo $AWS_ACCESS_KEY_ID
   
   echo "export AWS_SECRET_ACCESS_KEY=<secret_key>" >> ~/.bashrc && . ~/.bashrc
   echo $AWS_SECRET_ACCESS_KEY
   

7. Configure the AWS CLI:

   aws configure
   

   Specify the following:

   • AWS Access Key ID: Service account key_id you got earlier.
   • AWS Secret Access Key: Service account secret key (secret) you got earlier.
   • Default region name: Use the ru-central1 value.
   • Default output format: Leave empty.

8. Check your configuration:

   echo $AWS_ACCESS_KEY_ID
   echo $AWS_SECRET_ACCESS_KEY
   aws configure list
   

Create Managed Service for YDB databasesCreate Managed Service for YDB databases

Create a database named game-data to store the game data and a database named data-streams for a stream in Data Streams.

1. Create a serverless database named game-data:

   yc ydb database create game-data --serverless
   

   Result:

   done (8s)
   id: etn0ejcvmjm4********
   folder_id: b1geoelk7fld********
   created_at: "2023-03-30T15:01:19Z"
   name: game-data
   status: PROVISIONING
   endpoint: grpcs://ydb.serverless.yandexcloud.net:2135/?database=/ru-central1/b1gia87mbaom********/etn0ejcvmjm4********
   serverless_database:
     storage_size_limit: "53687091200"
   location_id: ru-central1
   ...
   

2. Save the endpoint value from the previous command output to the YDB_ENDPOINT variable. In our example, it is grpcs://ydb.serverless.yandexcloud.net:2135.

   echo "export YDB_ENDPOINT=<DB_Document_API_endpoint>" >> ~/.bashrc && . ~/.bashrc
   echo $YDB_ENDPOINT
   

3. Save the database value from the previous command output to the YDB_DATABASE variable. In our example, it is /ru-central1/b1gia87mbaom********/etn0ejcvmjm4********.

   echo "export YDB_DATABASE=<table_name>" >> ~/.bashrc && . ~/.bashrc
   echo $YDB_DATABASE
   

4. Create a serverless database named data-streams:

   yc ydb database create data-streams --serverless
   

   Result:

   done (7s)
   id: etn16k0e1757********
   folder_id: b1geoelk7fld********
   created_at: "2023-03-30T15:02:44Z"
   name: data-streams
   status: PROVISIONING
   endpoint: grpcs://ydb.serverless.yandexcloud.net:2135/?database=/ru-central1/b1gia87mbaom********/etn16k0e1757********
   serverless_database:
     storage_size_limit: "53687091200"
   location_id: ru-central1
   

5. Save the endpoint value from the previous command output to the YDB_DATA_STREAMS_ENDPOINT variable. In our example, it is grpcs://ydb.serverless.yandexcloud.net:2135.

   echo "export YDB_DATA_STREAMS_ENDPOINT=<DB_Document_API_endpoint>" >> ~/.bashrc && . ~/.bashrc
   echo $YDB_DATA_STREAMS_ENDPOINT
   

6. Save the database value from the previous command output to the YDB_DATA_STREAMS_DATABASE variable. In our example, it it /ru-central1/b1gia87mbaom********/etn16k0e1757********.

   echo "export YDB_DATA_STREAMS_DATABASE=<table_name>" >> ~/.bashrc && . ~/.bashrc
   echo $YDB_DATA_STREAMS_DATABASE
   

7. Make sure all configurations are correct:

   ydb \
     --endpoint $YDB_ENDPOINT \
     --database $YDB_DATABASE \
     --sa-key-file $SA_KEY_FILE \
   discovery whoami \
     --groups
   

   Result:

   User SID: ajeien4d11sc043********
   
   Group SIDs:
   all-users@well-known
   

Create a tableCreate a table

1. Navigate to the files directory in the yc-serverless-game folder.

2. Create a table using the db-example.sql file:

   ydb \
     --endpoint $YDB_ENDPOINT \
     --database $YDB_DATABASE \
     --sa-key-file $SA_KEY_FILE \
   scripting yql --file db-example.sql
   

3. Add a record for the initial configuration:

   ydb \
     --endpoint $YDB_ENDPOINT \
     --database $YDB_DATABASE \
     --sa-key-file $SA_KEY_FILE \
   scripting yql --file db-update.sql
   

4. Check the result:

   ydb \
     --endpoint $YDB_ENDPOINT \
     --database $YDB_DATABASE \
     --sa-key-file $SA_KEY_FILE \
   scheme describe Config
   

   Result:

   Columns:
   ┌────────────────────┬─────────┬────────┬─────┐
   | Name               | Type    | Family | Key |
   ├────────────────────┼─────────┼────────┼─────┤
   | name               | Utf8?   |        | K0  |
   | grid_cell_size     | Uint32? |        |     |
   | max_active_players | Uint8?  |        |     |
   | max_inactive_sec   | Int32?  |        |     |
   | player_size        | Uint32? |        |     |
   | transport          | Utf8?   |        |     |
   | world_size_x       | Uint32? |        |     |
   | world_size_y       | Uint32? |        |     |
   └────────────────────┴─────────┴────────┴─────┘
   
   Storage settings:
   Store large values in "external blobs": false
   
   Column families:
   ┌─────────┬──────┬─────────────┬────────────────┐
   | Name    | Data | Compression | Keep in memory |
   ├─────────┼──────┼─────────────┼────────────────┤
   | default |      | None        |                |
   └─────────┴──────┴─────────────┴────────────────┘
   
   Auto partitioning settings:
   Partitioning by size: true
   Partitioning by load: false
   Preferred partition size (Mb): 2048
   Min partitions count: 1
   

Create a stream in Data StreamsCreate a stream in Data Streams

echo $YDB_DATA_STREAMS_DATABASE

aws kinesis create-stream \
  --endpoint https://yds.serverless.yandexcloud.net \
  --stream-name $YDB_DATA_STREAMS_DATABASE/notify-state-change \
  --shard-count 1

Create a Yandex Lockbox secretCreate a Yandex Lockbox secret

1. Create a secret named game-secrets and inject the YDB_ENDPOINT and YDB_DATABASE values into it:

   yc lockbox secret create --name game-secrets \
     --description "The secrets for the serverless game" \
     --payload "[{'key': 'ydb_endpoint', 'text_value': $YDB_ENDPOINT},{'key': 'ydb_db', 'text_value': $YDB_DATABASE}]"
   

2. Save the ID of the new secret to the LOCKBOX_SECRET_ID variable:

   echo "export LOCKBOX_SECRET_ID=$(jq -r <<<  \
   "$(yc lockbox secret list --format json | jq '.[]' -c | grep game-secrets)" .id)"  \
   >> ~/.bashrc && . ~/.bashrc
   
   echo $LOCKBOX_SECRET_ID
   

3. Inject the TG_BOT_TOKEN value into the secret:

   yc lockbox secret add-version --id $LOCKBOX_SECRET_ID \
   --payload "[{'key': 'tg_bot_token', 'text_value': '$TG_BOT_TOKEN'}]"
   

4. Inject the keys into the secret (we will get their values later). For now, set them to null.

   yc lockbox secret add-version --id $LOCKBOX_SECRET_ID \
   --payload "[{'key': 'ymq_writer_key_id', 'text_value': 'null'},\
   {'key': 'ymq_writer_key_secret', 'text_value': 'null'},\
   {'key': 'ymq_capture_queue_url', 'text_value': 'null'},\
   {'key': 'yds_writer_key_id', 'text_value': 'null'},\
   {'key': 'yds_writer_key_secret', 'text_value': 'null'},\
   {'key': 'yds_state_change_stream', 'text_value': 'notify-state-change'},\
   {'key': 'yds_state_change_database', 'text_value': '$YDB_DATA_STREAMS_DATABASE'}]"
   

Deploy your projectDeploy your project

1. Navigate to the files directory in the yc-serverless-game folder.

2. Change the configuration for Object Storage. Since the bucket name must be unique, change it to a custom bucket name in the following files:

   • serverless.yaml:

     sls-game-files:
       type: yc::ObjectStorageBucket
     

   • upload-to-s3.ts in the scripts directory:

     Bucket: 'sls-game-files',
     

     For example, specify sls-game-files-example instead of sls-game-files.

3. Set the APP_ENV variable to build your project:

   echo "export APP_ENV=production" >> ~/.bashrc && . ~/.bashrc
   echo $APP_ENV
   

4. Build and deploy the project. In the yc-serverless-game root folder, run the following commands one by one:

   nvm use
   nvm install
   npm ci
   
   npm run build
   npm run deploy
   

Your working folder will contain the following resources once your project is deployed:

• Cloud Functions:

  • get-state
  • get-config
  • move
  • capture
  • state-change
  • login
  • auth
  • ws-connect
  • ws-message
  • ws-disconnect

• Service accounts:

  • functions-sa with the editor role
  • triggers-sa with the serverless.functions.invoker role
  • yds-reader-sa with the yds.admin role
  • yds-writer-sa with the yds.writer role
  • ymq-reader-sa with the ymq.reader role
  • ymq-writer-sa with the ymq.writer role
  • apigw-s3-viewer with the storage.viewer role
  • apigw-fn-caller with the serverless.functions.invoker role

• Object Storage bucket with the name you specified in serverless.yaml

• Message Queue named capturing-queue

Create access keys for the service accountsCreate access keys for the service accounts

During project deployment, the system created these service accounts:

• yds-writer-sa with the yds.writer role to write data to Data Streams.
• ymq-writer-sa with the ymq.writer role to write data to Message Queue.

1. Create a static access key for the yds-writer-sa service account:

   echo "export YDS_WRITER_SA_ID=$(jq -r <<<  \
   "$(yc iam service-account list --format json | jq '.[]' -c | grep yds-writer-sa)" .id)"  \
   >> ~/.bashrc && . ~/.bashrc
   
   yc iam access-key create --service-account-id $YDS_WRITER_SA_ID
   

   Result:

   access_key:
       id: ajeibet32197********
       service_account_id: ajehr6tv2eoo********
       created_at: "2023-03-13T10:20:58.471421425Z"
       key_id: YCASD3CT9mPCVFh3K********
   secret: YCNhBcdvfDdssIuBa-FDl6zZz0MSky********
   

2. Copy the key_id value and save it to the YDS_WRITER_KEY_ID variable:

   echo "export YDS_WRITER_KEY_ID=<key_ID>" >> ~/.bashrc && . ~/.bashrc
   echo $YDS_WRITER_KEY_ID
   

3. Copy the secret value and save it to the YDS_WRITER_KEY_SECRET variable:

   echo "export YDS_WRITER_KEY_SECRET=<secret>" >> ~/.bashrc && . ~/.bashrc
   echo $YDS_WRITER_KEY_SECRET
   

4. Create a static access key for the ymq-writer-sa service account:

   echo "export YMQ_WRITER_SA_ID=$(jq -r <<<  \
   "$(yc iam service-account list --format json | jq '.[]' -c | grep ymq-writer-sa)" .id)"  \
   >> ~/.bashrc && . ~/.bashrc
   
   yc iam access-key create --service-account-id $YMQ_WRITER_SA_ID
   

5. Copy the key_id value and save it to the YMQ_WRITER_KEY_ID variable:

   echo "export YMQ_WRITER_KEY_ID=<key_ID>" >> ~/.bashrc && . ~/.bashrc
   
   echo $YMQ_WRITER_KEY_ID
   

6. Copy the secret value and save it to the YMQ_WRITER_KEY_SECRET variable:

   echo "export YMQ_WRITER_KEY_SECRET=<secret>" >> ~/.bashrc && . ~/.bashrc
   echo $YMQ_WRITER_KEY_SECRET
   

Create a new secret version and deploy your project againCreate a new secret version and deploy your project again

1. Inject new values into the secret named game-secrets:

   1. In the management console, select your working folder.

   2. Select Message Queue.

   3. Select capturing-queue.

   4. Copy the value from the URL field and save it to the YMQ_CAPTURE_QUEUE_URL variable:

      echo "export YMQ_CAPTURE_QUEUE_URL=<URL>" >> ~/.bashrc && . ~/.bashrc
      

   5. Check the variable values to inject into the secret:

      echo $LOCKBOX_SECRET_ID
      echo $YMQ_WRITER_KEY_ID
      echo $YMQ_WRITER_KEY_SECRET
      echo $YDS_WRITER_KEY_ID
      echo $YDS_WRITER_KEY_SECRET
      echo $YMQ_CAPTURE_QUEUE_URL
      

   6. Inject the values into the secret:

      yc lockbox secret add-version --id $LOCKBOX_SECRET_ID \
      --payload "[{'key': 'ymq_writer_key_id', 'text_value': '$YMQ_WRITER_KEY_ID'},\
      {'key': 'ymq_writer_key_secret', 'text_value': '$YMQ_WRITER_KEY_SECRET'},\
      {'key': 'ymq_capture_queue_url', 'text_value': '$YMQ_CAPTURE_QUEUE_URL'},\
      {'key': 'yds_writer_key_id', 'text_value': '$YDS_WRITER_KEY_ID'},\
      {'key': 'yds_writer_key_secret', 'text_value': '$YDS_WRITER_KEY_SECRET'}]"
      

2. Navigate to the yc-serverless-game root folder and deploy your project again:

   npm run deploy
   

Create an API GatewayCreate an API Gateway

During project deployment, the system created these service accounts:

• apigw-s3-viewer with the storage.viewer role to read objects from the Object Storage bucket.
• apigw-fn-caller with the functions.functionInvoker role to invoke Cloud Functions.

1. Save the IDs of the apigw-s3-viewer and apigw-fn-caller service accounts to the APIGW_S3_VIEWER_ID and APIGW_FN_CALLER_ID variables:

   echo "export APIGW_S3_VIEWER_ID=$(jq -r <<<  \
   "$(yc iam service-account list --format json | jq '.[]' -c | grep apigw-s3-viewer)" .id)"  \
   >> ~/.bashrc && . ~/.bashrc
   
   echo "export APIGW_FN_CALLER_ID=$(jq -r <<<  \
   "$(yc iam service-account list --format json | jq '.[]' -c | grep apigw-fn-caller)" .id)"  \
   >> ~/.bashrc && . ~/.bashrc
   

2. Modify the API gateway specification. Navigate to the files directory in the yc-serverless-game folder and run the following command:

   cp apigw-example.yml apigw.yml
   

3. Get the IDs of the resources you created in the previous steps:

   echo $APIGW_S3_VIEWER_ID
   echo $APIGW_FN_CALLER_ID
   
   yc storage bucket list
   yc serverless function list
   

4. Edit the apigw.yml file as follows:

   1. In all bucket: serverless-game-files lines, replace the bucket name with the custom one.
   2. In all service_account_id: <sa-id-for-object-storage> lines, replace <sa-id-for-object-storage> with the $APIGW_S3_VIEWER_ID value.
   3. In all service_account_id: <sa-id-for-functions> lines, replace <sa-id-for-functions> with the $APIGW_FN_CALLER_ID value.
   4. In line 58, replace <yandex-cloud-nodejs-dev-get-state-function-id> with the yandex-cloud-nodejs-dev-get-state function ID.
   5. In line 65, replace <yandex-cloud-nodejs-dev-get-config-function-id> with the yandex-cloud-nodejs-dev-get-config function ID.
   6. In line 72, replace <yandex-cloud-nodejs-dev-move-function-id> with the yandex-cloud-nodejs-dev-move function ID.
   7. In line 79, replace <yandex-cloud-nodejs-dev-login-function-id> with the yandex-cloud-nodejs-dev-login function ID.
   8. In line 101, replace <yandex-cloud-nodejs-dev-ws-message-function-id> with the yandex-cloud-nodejs-dev-ws-message function ID.
   9. In line 106, replace <yandex-cloud-nodejs-dev-ws-connect-function-id> with the yandex-cloud-nodejs-dev-ws-connect function ID.
   10. In line 111, replace <yandex-cloud-nodejs-dev-ws-disconnect-function-id> with the yandex-cloud-nodejs-dev-ws-disconnect function ID.
   11. In line 118, replace <yandex-cloud-nodejs-dev-auth-function-id> with the yandex-cloud-nodejs-dev-auth function ID.

5. Deploy an API Gateway instance:

   yc serverless api-gateway create \
     --name serverless-game-api \
     --spec=apigw.yml \
     --description "for serverless-game-api"
   

   In case of an error in the API gateway specification, fix it and run this command:

   yc serverless api-gateway update \
     --name serverless-game-api \
     --spec=apigw.yml 
   

Add your domain to the Telegram botAdd your domain to the Telegram bot

1. Run this command:

   yc serverless api-gateway get --name serverless-game-api
   

2. Copy your API gateway's service domain. You can find it in the domain field of the previous command output.

3. In Telegram, find BotFather and type the /setdomain command.

4. Select your bot from the list and send it your API gateway's service domain. Add https:// before the domain name. For example, if your API gateway's service domain is d5dm1lba80md********.i9******.apigw.yandexcloud.net, the URL will be https://d5dm1lba80md********.i9******.apigw.yandexcloud.net.

Test your applicationTest your application

Follow the link you sent to the Telegram bot, sign in, and open the game.

The game offers player statistics. If the API gateway's service domain is d5dm1lba80md********.i9******.apigw.yandexcloud.net, the statistics for all players will be available at https://d5dm1lba80md********.i9******.apigw.yandexcloud.net/stats.html.

How to delete the resources you createdHow to delete the resources you created

To stop paying for the resources you created:

• Delete the Managed Service for YDB databases.
• Delete the stream in Data Streams.
• Delete the Yandex Lockbox secret.
• Delete all objects from the bucket and then delete the empty Object Storage bucket.
• Delete the API Gateway.
• Delete the Cloud Functions.
• Delete the Message Queue.