|
| 1 | +--- |
| 2 | +title: Integrate - Build a real-time collaborative whiteboard using Azure Web PubSub and deploy it to Azure App Service |
| 3 | +description: A how-to guide about how to use Azure Web PubSub to enable real-time collaboration on a digital whiteboard and deploy as a Web App using Azure App Service |
| 4 | +author: KevinGuo-ed |
| 5 | +ms.author: kevinguo |
| 6 | +ms.service: azure-web-pubsub |
| 7 | +ms.custom: devx-track-azurecli |
| 8 | +ms.topic: tutorial |
| 9 | +ms.date: 05/17/2023 |
| 10 | +--- |
| 11 | +# How-to: build a real-time collaborative whiteboard using Azure Web PubSub and deploy it to Azure App Service |
| 12 | + |
| 13 | +A new class of applications is reimagining what modern work could be. While [Microsoft Word](https://www.microsoft.com/microsoft-365/word) brings editors together, [Figma](https://www.figma.com) gathers up designers on the same creative endeavor. This class of applications builds on a user experience that makes us feel connected with our remote collaborators. From a technical point of view, user's activities need to be synchronized across users' screens at a low latency. |
| 14 | + |
| 15 | +## Overview |
| 16 | +In this how-to guide, we take a cloud-native approach and use Azure services to build a real-time collaborative whiteboard and we deploy the project as a Web App to Azure App Service. The whiteboard app is accessible in the browser and allows anyone can draw on the same canvas. |
| 17 | + |
| 18 | +:::image type="content" source="./media/howto-integrate-app-service/result.gif" alt-text="Gif of finished project."::: |
| 19 | + |
| 20 | +> [!div class="nextstepaction"] |
| 21 | +> [Check out live whiteboard demo](https://azure.github.io/azure-webpubsub/demos/whiteboard) |
| 22 | +
|
| 23 | +### Architecture |
| 24 | + |
| 25 | +|Azure service name | Purpose | Benefits | |
| 26 | +|----------------------|-------------------|------------------| |
| 27 | +|[Azure App Service](https://learn.microsoft.com/azure/app-service/) | Provides the hosting environment for the backend application, which is built with [Express](https://expressjs.com/) | Fully managed environment for application backends, with no need to worry about infrastructure where the code runs |
| 28 | +|[Azure Web PubSub](https://learn.microsoft.com/azure/azure-web-pubsub/overview) | Provides low-latency, bi-directional data exchange channel between the backend application and clients | Drastically reduces server load by freeing server from managing persistent WebSocket connections and scales to 100 K concurrent client connections with just one resource |
| 29 | + |
| 30 | +:::image type="content" source="./media/howto-integrate-app-service/architecture.jpg" alt-text="Architecture diagram of the collaborative whiteboard app."::: |
| 31 | + |
| 32 | +## Prerequisites |
| 33 | +You can find detailed explanation of the [data flow](#data-flow) at the end of this how-to guide as we're going to focus on building and deploying the whiteboard app first. |
| 34 | + |
| 35 | +In order to follow the step-by-step guide, you need |
| 36 | +> [!div class="checklist"] |
| 37 | +> * An [Azure](https://portal.azure.com/) account. If you don't have an Azure subscription, create an [Azure free account](https://azure.microsoft.com/free/?ref=microsoft.com&utm_source=microsoft.com&utm_medium=docs&utm_campaign=visualstudio) before you begin. |
| 38 | +> * [Azure CLI](/cli/azure/install-azure-cli) (version 2.29.0 or higher) or [Azure Cloud Shell](../cloud-shell/quickstart.md) to manage Azure resources. |
| 39 | +
|
| 40 | +## Create Azure resources using Azure CLI |
| 41 | +### 1. Sign in |
| 42 | +1. Sign in to Azure CLI by running the following command. |
| 43 | + ```azurecli-interactive |
| 44 | + az login |
| 45 | + ``` |
| 46 | +
|
| 47 | +1. Create a resource group on Azure. |
| 48 | + ```azurecli-interactive |
| 49 | + az group create \ |
| 50 | + --location "westus" \ |
| 51 | + --name "whiteboard-group" |
| 52 | + ``` |
| 53 | +
|
| 54 | +### 2. Create a Web App resource |
| 55 | +1. Create a free App Service plan. |
| 56 | + ```azurecli-interactive |
| 57 | + az appservice plan create \ |
| 58 | + --resource-group "whiteboard-group" \ |
| 59 | + --name "demo" \ |
| 60 | + --sku FREE |
| 61 | + --is-linux |
| 62 | + ``` |
| 63 | +
|
| 64 | +1. Create a Web App resource |
| 65 | + ```azurecli-interactive |
| 66 | + az webapp create \ |
| 67 | + --resource-group "whiteboard-group" \ |
| 68 | + --name "whiteboard-app" \ |
| 69 | + --plan "demo" \ |
| 70 | + --runtime "NODE:18-lts" |
| 71 | + ``` |
| 72 | +
|
| 73 | +### 3. Create a Web PubSub resource |
| 74 | +1. Create a Web PubSub resource. |
| 75 | + ```azurecli-interactive |
| 76 | + az webpubsub create \ |
| 77 | + --name "whiteboard-app" \ |
| 78 | + --resource-group "whiteboard-group" \ |
| 79 | + --location "westus" \ |
| 80 | + --sku Free_F1 |
| 81 | + ``` |
| 82 | +
|
| 83 | +1. Show and store the value of `primaryConnectionString` somewhere for later use. |
| 84 | + ```azurecli-interactive |
| 85 | + az webpubsub key show \ |
| 86 | + --name "whiteboard-app" \ |
| 87 | + --resource-group "whiteboard-group" |
| 88 | + ``` |
| 89 | +--- |
| 90 | +## Get the application code |
| 91 | +Run the following command to get a copy of the application code. You can find detailed explanation of the [data flow](#data-flow) at the end of this how-to guide. |
| 92 | +```bash |
| 93 | +git clone https://github.com/Azure/awps-webapp-sample.git |
| 94 | +``` |
| 95 | + |
| 96 | +## Deploy the application to App Service |
| 97 | +1. App Service supports many deployment workflows. For this guide, we're going to deploy a ZIP package. Run the following commands to prepare the ZIP. |
| 98 | + ```bash |
| 99 | + npm install |
| 100 | + npm run build |
| 101 | + zip -r app.zip * |
| 102 | + ``` |
| 103 | + |
| 104 | +2. Use the following command to deploy it to Azure App Service. |
| 105 | + ```azurecli-interactive |
| 106 | + az webapp deployment source config-zip \ |
| 107 | + --resource-group "whiteboard-group" \ |
| 108 | + --name "whiteboard-app" \ |
| 109 | + --src app.zip |
| 110 | + ``` |
| 111 | + |
| 112 | +3. Set Azure Web PubSub connection string in the application settings. Use the value of `primaryConnectionString` you stored from an earlier step. |
| 113 | + ```azurecli-interactive |
| 114 | + az webapp config appsettings set \ |
| 115 | + --resource-group "whiteboard-group" \ |
| 116 | + --name "whiteboard-app" \ |
| 117 | + --setting Web_PubSub_ConnectionString="<primaryConnectionString>" |
| 118 | + ``` |
| 119 | + |
| 120 | +## Configure upstream server to handle events coming from Web PubSub |
| 121 | +Whenever a client sends a message to Web PubSub service, the service sends an HTTP request to an endpoint you specify. This mechanism is what your backend server uses to further process messages, for example, if you can persist messages in a database of choice. |
| 122 | + |
| 123 | +As is with HTTP requests, Web PubSub service needs to know where to locate your application server. Since the backend application is now deployed to App Service, we get a publically accessible domain name for it. |
| 124 | +1. Show and store the value of `name` somewhere. |
| 125 | + ```azurecli-interactive |
| 126 | + az webapp config hostname list \ |
| 127 | + --resource-group "whiteboard-group" |
| 128 | + --webapp-name "whiteboard-app" |
| 129 | + ``` |
| 130 | + |
| 131 | +1. The endpoint we decided to expose on the backend server is [`/eventhandler`](https://github.com/Azure/awps-webapp-sample/blob/main/whiteboard/server.js#L17) and the `hub` name for whiteboard app [`"sample_draw"`](https://github.com/Azure/awps-webapp-sample/blob/main/whiteboard/server.js#l14) |
| 132 | + ```azurecli-interactive |
| 133 | + az webpubsub hub create \ |
| 134 | + --resource-group "whiteboard-group" \ |
| 135 | + --name "whiteboard-app" \ |
| 136 | + --hub-name "sample_draw" \ |
| 137 | + --event-handler url-template="https://<Replace with the hostname of your Web App resource>/eventhandler" user-event-pattern="*" system-event="connected" system-event="disconnected" |
| 138 | + ``` |
| 139 | +> [!IMPORTANT] |
| 140 | +> `url-template` has three parts: protocol + hostname + path, which in our case is `https://<The hostname of your Web App resource>/eventhandler`. |
| 141 | + |
| 142 | +## View the whiteboard app in a browser |
| 143 | +Now head over to your browser and visit your deployed Web App. It's recommended to have multiple browser tabs open so that you can experience the real-time collaborative aspect of the app. Or better, share the link with a colleague or friend. |
| 144 | +
|
| 145 | +## Data flow |
| 146 | +### Overview |
| 147 | +The data flow section dives deeper into how the whiteboard app is built. The whiteboard app has two transport methods. |
| 148 | +- HTTP service written as an Express app and hosted on App Service. |
| 149 | +- WebSocket connections managed by Azure Web PubSub. |
| 150 | +
|
| 151 | +By using Azure Web PubSub to manage WebSocket connections, the load on the Web App is reduced. Apart from authenticating the client and serving images, the Web App isn't involved synchronizing drawing activities. A client's drawing activities are directly sent to Web PubSub and broadcasted to all clients in a group. |
| 152 | +
|
| 153 | +At any point in time, there maybe more than one client drawing. If the Web App were to manage WebSocket connections on its own, it needed to broadcast every drawing activity to all other clients. The huge traffic and processing are a large burden to the server. |
| 154 | +
|
| 155 | +:::row::: |
| 156 | + :::column::: |
| 157 | + The client, built with [Vue](https://vuejs.org/), makes an HTTP request for a Client Access Token to an endpoint `/negotiate`. The backend application is an [Express app](https://expressjs.com/) and hosted as a Web App using Azure App Service. |
| 158 | + :::column-end::: |
| 159 | + :::column::: |
| 160 | + :::image type="content" source="./media/howto-integrate-app-service/dataflow-1.jpg" alt-text="Screenshot of step one of app data flow." lightbox="./media/howto-integrate-app-service/dataflow-1.jpg"::: |
| 161 | + :::column-end::: |
| 162 | +:::row-end::: |
| 163 | +
|
| 164 | +:::row::: |
| 165 | + :::column::: |
| 166 | + When the backend application successfully [returns the Client Access Token](https://github.com/Azure/awps-webapp-sample/blob/main/whiteboard/server.js#L62) to the connecting client, the client uses it to establish a WebSocket connection with Azure Web PubSub. |
| 167 | + :::column-end::: |
| 168 | + :::column::: |
| 169 | + :::image type="content" source="./media/howto-integrate-app-service/dataflow-2.jpg" alt-text="Screenshot of step two of app data flow." lightbox="./media/howto-integrate-app-service/dataflow-2.jpg"::: |
| 170 | + :::column-end::: |
| 171 | +:::row-end::: |
| 172 | +
|
| 173 | +:::row::: |
| 174 | + :::column::: |
| 175 | + If the handshake with Azure Web PubSub is successful, the client is added to a group named `draw`, effectively subscribing to messages published to this group. Also, the client is given the permission to send messages to the [`draw` group](https://github.com/Azure/awps-webapp-sample/blob/main/whiteboard/server.js#L64). |
| 176 | + :::column-end::: |
| 177 | + :::column::: |
| 178 | + :::image type="content" source="./media/howto-integrate-app-service/dataflow-3.jpg" alt-text="Screenshot of step three of app data flow." lightbox="./media/howto-integrate-app-service/dataflow-3.jpg"::: |
| 179 | + :::column-end::: |
| 180 | +:::row-end::: |
| 181 | +> [!NOTE] |
| 182 | +> To keep this how-to guide focused, all connecting clients are added to the same group named `draw` and is given the permission to send messages to this group. To manage client connections at a granular level, see the full references of the APIs provided by Azure Web PubSub. |
| 183 | +
|
| 184 | +:::row::: |
| 185 | + :::column::: |
| 186 | + Azure Web PubSub notifies the backend application that a client has connected. The backend application handles the `onConnected` event by calling the `sendToAll()`, with a payload of the latest number of connected clients. |
| 187 | + :::column-end::: |
| 188 | + :::column::: |
| 189 | + :::image type="content" source="./media/howto-integrate-app-service/dataflow-4.jpg" alt-text="Screenshot of step four of app data flow." lightbox="./media/howto-integrate-app-service/dataflow-4.jpg"::: |
| 190 | + :::column-end::: |
| 191 | +:::row-end::: |
| 192 | +> [!NOTE] |
| 193 | +> It is important to note that if there are a large number of online users in the `draw` group, with **a single** network call from the backend application, all the online users will be notified that a new user has just joined. This drastically reduces the complexity and load of the backend application. |
| 194 | +
|
| 195 | +:::row::: |
| 196 | + :::column::: |
| 197 | + As soon as a client establishes a persistent connection with Web PubSub, it makes an HTTP request to the backend application to fetch the latest shape and background data at [`/diagram`](https://github.com/Azure/awps-webapp-sample/blob/main/whiteboard/server.js#L70). An HTTP service hosted on App Service can be combined with Web PubSub. App Service takes care serving HTTP endpoints, while Web PubSub takes care of managing WebSocket connections. |
| 198 | + :::column-end::: |
| 199 | + :::column::: |
| 200 | + :::image type="content" source="./media/howto-integrate-app-service/dataflow-5.jpg" alt-text="Screenshot of step five of app data flow." lightbox="./media/howto-integrate-app-service/dataflow-5.jpg"::: |
| 201 | + :::column-end::: |
| 202 | +:::row-end::: |
| 203 | +
|
| 204 | +:::row::: |
| 205 | + :::column::: |
| 206 | + Now that the clients and backend application have two ways to exchange data. One is the conventional HTTP request-response cycle and the other is the persistent, bi-directional channel through Web PubSub. The drawing actions, which originate from one user and need to be broadcasted to all users as soon as it takes place, are delivered through Web PubSub. It doesn't require involvement of the backend application. |
| 207 | + :::column-end::: |
| 208 | + :::column::: |
| 209 | + :::image type="content" source="./media/howto-integrate-app-service/dataflow-6.jpg" alt-text="Screenshot of step six of app data flow." lightbox="./media/howto-integrate-app-service/dataflow-6.jpg"::: |
| 210 | + :::column-end::: |
| 211 | +:::row-end::: |
| 212 | + |
| 213 | +## Clean up resources |
| 214 | +Although the application uses only the free tiers of both services, it's best practice to delete resources if you no longer need them. You can delete the resource group along with the resources in it using following command, |
| 215 | +
|
| 216 | +```azurecli-interactive |
| 217 | +az group delete |
| 218 | + --name "whiteboard-group" |
| 219 | +``` |
| 220 | +
|
| 221 | +## Next steps |
| 222 | +> [!div class="nextstepaction"] |
| 223 | +> [Check out more demos built with Web PubSub](https://azure.github.io/azure-webpubsub/demos/chat) |
| 224 | +
|
0 commit comments