Documentation (#1)

* Added draft documents

- Added prerequisites
- Added how to run the solution locally
- Added how to run the solution in Azure

* Updated readme

* Deleted unnecessary document

* Updated documentation

- Updated folder structure
- How to run the solution locally: added steps to explain how to create ngrok config file
- How to run the solution in azure: added new documents
- Common: added step to explain where to put the required domain certificate for NGINX

* Updated nginx guide

- Updated nginx configuration
- Fixed RTMP url in bash commands

* Updated how to run the solution locally readme

- Renamed placholders and change their descriptions
- Removed unnecessary descriptions

* Minor fix

* Uppdated how to run the solution in azure

- Added how to create containers needed by the solution in cosmos db
- Added template of the service item the user must add in the service cosmos db container before running the solution for the first time.
- Completed the document that explains how to deploy the Management API
- Improved the introduction of the Azure SDK Service Principal document
- Added section about how to add members in the Security Group document
- Updated references from Bot Channels Registration to Azure Bot in all documents
- Fixed typos and broken links

* Updated how to run the solution in azure documents

* WIP - Updated how to run the solution in azure

* Updated how to run the solution in azure documents

* Updated documentation

* Updated documents

- Minor feedback
- Added document that explains how to get access token
- Updated document references
- Added document that explains how to test the azure function

* Updated documentation

README.md

@@ -79,15 +79,11 @@ This solution currently has some limitations:
 
 - There are some restrictions on using this solution to record content from a Microsoft Teams meeting, which are inherited from the [Graph Communications Bot Media SDK](https://microsoftgraph.github.io/microsoft-graph-comms-samples/docs/bot_media/index.html#accompanying-documentation). Check the documentation of the SDK for more information.
 
-## Getting started
+## Getting Started
 
-TBC
+This section will guide you through the process of configuring the solution to run it locally and/or in azure.
 
-## Understanding the architecture
-
-TBC
-
-## Exploring the repository
+### Exploring the repository
 
 The repository is structured in the following directories:
 - **src**: Contains the source code of the application.
@@ -96,6 +92,21 @@ The repository is structured in the following directories:
     - **OrchestratorFunction**: Contains the Azure function in charge of managing the status of the VMs.
 - **docs**: Contains the documentation on the solution (TBC).
 
+
+### How to run the solution
+- [Prerequisites](docs/prerequisites/readme.md)
+- [How to run the solution locally](docs/how-to-run-the-solution-locally/README.md)
+- [How to run the solution in Azure](docs/how-to-run-the-solution-in-azure/README.md)
+
+## Understanding the architecture
+
+TBC
+
+## About
+
+{{PENDING}}
+
+
 ## Contributing
 
 This project welcomes contributions and suggestions.  Most contributions require you to agree to a

docs/common/install_and_configure_nginx_with_rtmp_module_on_windows.md

@@ -0,0 +1,211 @@
+# How to Install and configure NGINX with RTMP module on Windows (DRAFT)
+
+
+## Getting Started
+
+To support RTMP injection in {{insert the name of the solution}} we need to configure NGINX in the host machine. The objective of this guide is to explain how to correctly install and configure NGINX with the RTMP module in Windows, how to inject a live broadcast locally, and how to run NGINX as a Windows service.
+
+>  **NOTE**: We are going to use NGINX version 1.14.1. It has not been tested with recent versions.
+
+## Installation
+
+Download as a zip NGINX with RTMP module from the following [GitHub repository](https://github.com/illuspas/nginx-rtmp-win32).
+
+|![Nginx GitHub repository](images/nginx_repository.png)|
+|:--:|
+|*NGINX with RTMP module repository*|
+
+
+Before editing the `nginx.config` file, to support RTMPS we must copy the SSL certificate (we've mentioned as prerequisite [here](../prerequisites/readme.md)) and its key into the host machine. (e.g.: C:\certs)
+
+| ![Certs](images/cert-files.png)|
+|:--:|
+|*Example certs*|
+
+After that, unzip the file in a location of preference (e.g: C:\), open `nginx.config` file with your text editor of preferences and replace its content with the following code snippet:
+
+```nginx
+worker_processes  1;
+error_log  logs/error.log;
+error_log  logs/error.log  notice;
+error_log  logs/error.log  info;
+pid        logs/nginx.pid;
+
+events {
+    worker_connections  8192;
+    # max value 32768, nginx recycling connections+registry optimization =
+    #   this.value * 20 = max concurrent connections currently tested with one worker
+    #   C1000K should be possible depending there is enough ram/cpu power
+    # multi_accept on;
+}
+
+stream {
+    upstream publish {
+        server 127.0.0.1:29361;
+    }
+    server {
+        listen 2936 ssl;        # additional port for publishing
+        proxy_pass publish;
+        ssl_certificate c:\\certs\\fullchain.pem; #root path where your certificate is located e.g.: C:\certs\fullchain.pem
+        ssl_certificate_key c:\\certs\\privkey.pem; #root path where your certificate key is located e.g.: C:\certs\privkey.pem
+
+        allow all;
+    }
+
+    upstream live {
+        server 127.0.0.1:29351;
+    }
+    server {
+        listen 2935 ssl;        # standard RTMP(S) port
+        proxy_pass live;
+        ssl_certificate c:\\certs\\fullchain.pem; #root path where your certificate is located e.g.: C:\certs\fullchain.pem
+        ssl_certificate_key c:\\certs\\privkey.pem; #root path where your certificate key is located e.g.: C:\certs\privkey.pem
+
+        allow all;              # this is public (this is also the default)
+    }
+}
+
+rtmp {
+    server {
+        listen 127.0.0.1:29361;
+        chunk_size 4096;
+
+        application secure-ingest{
+            live on;
+            record off;
+
+	        on_publish http://localhost/api/bot/validate-stream-key;
+
+            allow publish 127.0.0.1;  # publishing through rtmps://rtmp.example.com:1936
+            allow play 127.0.0.1;     # for the pull from rtmp://localhost:19351/live
+        }
+    }
+
+    server {
+        listen 127.0.0.1:29351;
+        chunk_size 4096;
+
+        application live {
+            live on;
+            record off;
+            deny publish all;         # no need to publish on /live -- IMPORTANT!!!
+            allow play 127.0.0.1;     # playing through rtmps://rtmp.example.com:1935/live
+
+            pull rtmp://127.0.0.1:29361/secure-ingest;
+        }
+    }
+
+    server {
+        listen 1936;
+        chunk_size 4096;
+        application ingest {
+            live on;
+            record off;
+	    
+	        on_publish http://localhost/api/bot/validate-stream-key;
+        }
+        application test-endpoint {
+            live on;
+            record off;
+        }
+    }
+}
+
+http {
+    server {
+        listen      8080;
+		
+        location / {
+            root html;
+        }
+		
+        location /stat {
+            rtmp_stat all;
+            rtmp_stat_stylesheet stat.xsl;
+        }
+
+        location /stat.xsl {
+            root html;
+        }
+    }
+}
+```
+
+## Test NGINX server configuration
+
+>  **NOTE**: To test the NGINX server we will use GStreamer to create a pipeline that captures the audio and video of our PC and pushes it into the NGINX server. If you want to use other tool like OBS, feel free to skip this section.
+
+
+To start testing the NGINX server, we must open a terminal window, navigate to the NGINX root folder and execute `nginx.exe`.
+
+![Open Nginx](images/open_nginx.png)
+
+Once the server is running, we are going to locally test the RTMP endpoint by injecting content with GStreamer.
+
+Open a new command line window, and execute the following command:
+
+```bash
+gst-device-monitor-1.0
+```
+
+### List of found devices
+
+![Nginx gst device monitor](images/nginx_device_monitor.png)
+
+The command will prompt you with a list of input and output multimedia devices. We must identify the audio input device we will be using. We must search for a device with **Audio/Source** class where its **device.api** property equals to **wasapi**, and copy the value of **device.strid**.
+
+![wasapi device](images/nginx_wasapi_device.png)
+
+Once we identified the device and copied its id value, we need to run the following command (GStreamer CLI pipeline) to start capturing the video from your webcam and the audio of the selected device, and process it so we can inject it as an RTMP stream into the RTMP server.
+
+```bash
+gst-launch-1.0 wasapisrc device="{{device-strid}}" ! audioconvert ! avenc_aac ! aacparse ! queue ! mux. autovideosrc ! "video/x-raw, format=YUY2, width=320, height=180, framerate=30/1" ! videoconvert ! x264enc tune=zerolatency key-int-max=60 bitrate=2500 ! queue ! mux. flvmux name=mux streamable=true latency=500000000 ! rtmpsink location=rtmp://localhost:1936/test-endpoint/1
+```
+> **NOTE:** Replace the placheholder **{{device-strid}}** with the **device.strid** value we copied before.
+
+To validate the server and GStreamer are correctly working, we must start consuming the live endpoint with a player.
+
+**Using GStreamer**
+
+```bash
+gst-launch-1.0 rtmpsrc location=rtmp://localhost:1936/test-endpoint/1 ! decodebin name=decoder ! queue ! videoconvert ! autovideosink decoder. ! queue ! audioconvert ! audioresample ! autoaudiosink
+```
+Or
+
+
+```bash
+gst-launch-1.0 playbin uri=rtmp://localhost:1936/test-endpoint/1
+```
+
+![Using GStreamer](images/nginx_using_gstreamer.png)
+
+**Ffplay**
+```bash
+ffplay.exe rtmp://localhost:1936/test-endpoint/1
+```
+![Ffplay](images/nginx_ffplay.png)
+
+**VLC Player**
+
+> **NOTE**: Make sure you have a sufficiently recent version of VLC. RTMP streaming is supported in VLC versions 1.1 and later; you can download the most recent version by pointing your browser to [videolan.org](https://www.videolan.org/) and clicking **Download VLC**. Follow the on-screen instructions to download and install the program.
+
+Once VLC is installed, follow these steps:
+1. Open VLC's ***Media*** menu and click **Open Network Stream**, or simply hold down **CTRL** and press **N**.
+
+1. Paste the URL of the stream you want to watch, with the following format: `rtmp://localhost:1936/test-endpoint/1` in the **Please enter a network URL** box.  
+![](images/nginx_vlc_player.png)
+
+1. Click the **Play** button.
+
+## Run NGINX as a Windows Service
+In order to run NGINX as Windows Service is necessary to wrap the executable file into a Windows Service using an external program.
+
+To do so, we can use the [nssm](https://nssm.cc/) tool and execute it in the PC or VM where we want to install the service.  Download the nssm tool  ([download link](https://nssm.cc/download)), unzip the package, and execute the tool from the command line.
+
+Once the tool is open, set the path for the NGINX executable file and click on the **Install Service** button. After receiving the confirmation message the service is ready to start.
+
+![Install nginx](images/install_nginx.png)
+
+The first time, the service does not run automatically. We must initialize the service from the Windows services manager or, restart the machine.
+
+![](images/nginx_as_windows_service.png)

docs/how-to-run-the-solution-in-azure/README.md

@@ -0,0 +1,69 @@
+# How to Run the Solution in Azure
+
+## Introduction
+
+This document describes the resources that must be created and configured to run the solution in Azure. This includes:
+
+- App Registrations for authentication in different components in Azure AD tenant:
+    - [App Registrations](app_registrations.md#app-registrations):
+        - [Bot Service API](app_registrations.md#how-to-setup-bot-service-api-application-registration).
+        - [Bot Service Client](app_registrations.md#how-to-setup-bot-service-client-application-registration).
+        - [Management API](app_registrations.md#how-to-setup-management-api-application-registration).
+        - [Azure SDK Service Principal](azure_sdk_service_principal.md).
+    - [Security Group](security_group.md).
+- Resource groups used to deploy and configure the solution: 
+    - Architecture resource group:
+        - [Application Insights](application_insights.md).
+        - [Storage account](storage_account.md).
+        - [Cosmos DB](cosmos_db.md).
+        - [Web App and App service plan](web_app_and_app_service_plan.md).
+        - [Function App and App service plan](function_app_and_app_service_plan.md).
+    - Virtual Machine resource group:
+        - [Virtual Machine](bot_service_virtual_machine.md).
+        - [Event Grid](configure_event_grid.md).
+- Components Deployment:
+    - [Deploy the Web App into the Azure App Service](deploy_web_app.md).
+    - [Deploy the Function App into the Azure Function App Service](deploy_function_app.md).
+- Testing the environment:
+    - [How to configure/register the Service](add_service.md).
+    - [How to test the Management API](test_web_app.md)
+    - [How to test the Orchestrator Function](test_function_app.md)
+
+## App Registrations for authentication in different components in Azure AD tenant
+To secure and connect several of the resources used for the solution, we need to create several app registrations, each with its own permissions and settings. Several of the following instructions include creating application credentials. We recommend creating a Key Vault resource in Azure to store these credentials securely. We also recommend keeping track of the application IDs generated for each app registration to simplify the configuration of the applications during the project.  
+
+- [App Registrations](app_registrations.md#app-registrations).
+- [Security Group](security_group.md).
+
+## Resources used to deploy and configure the solution:
+
+### Resource Groups 
+To prepare the cloud environment, we need to create multiple resources which must be separated according to the different components of the solution. For that, it is necessary to create two **resource groups**, both in the same **region** (e.g., **West US 2**). 
+
+- **`resource-group-name`-bot**: This group will contain the rest of the resources related to the APIs, functions, database, and web UI used to operate the solution.
+
+- **`resource-group-name`-bot-vm**: This group will be used to contain the resources related to the virtual machine that will host the core components of the application in Azure. 
+
+> NOTE: It is suggested that `resource-group-name` be replaced by a name in line with the project.
+
+To create the resource groups, check the [Create resource groups](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal#create-resource-groups) documentation.
+
+### Architecture resource group
+
+The following resources are used to manage the application and the bot. All these resources should be created in the `resource-group-name`-bot resource group:
+
+- [Application Insights](application_insights.md).
+- [Storage account](storage_account.md).
+- [Cosmos DB](cosmos_db.md#cosmos-db-database).
+- [Web App and App service plan](web_app_and_app_service_plan.md).
+- [Function App and App service plan](function_app_and_app_service_plan.md).
+
+
+### Virtual Machine resource group
+
+The following resources form the core part of the solution, which is charge of connecting to the call and extract and inject the media feeds from the Teams Meeting call. 
+All these resources should be created in the `resource-group-name`-bot-vm resource group. 
+The app registration that was created to manage the state of the VM must be given access to this resource group with the Contributor role. This can be done in the **Access control (IAM)** menu of the resource group.
+
+- [Virtual Machine](bot_service_virtual_machine.md).
+- [Event Grid](configure_event_grid.md##how-to-configure-event-grid).

docs/how-to-run-the-solution-in-azure/add_service.md

@@ -0,0 +1,60 @@
+# How to Add the Service 
+
+## Introduction
+In order to start using the Azure environment once all the components have been deployed and configured, it is necessary to configure/register a service into the Cosmos DB.  
+
+## Dependencies
+To configure/register the service, the following dependencies need to be created:
+
+- [Management API ](deploy_web_app.md).
+- [BotOrchestrator deployed](deploy_function_app.md).
+- [Cosmos DB](cosmos_db.md).
+
+>**NOTE**: The Web and the Function Apps not only need to be created but also both components (Management API and Orchestrator Function) need to be deployed and configured.
+
+### Configure/Register
+The service is configured/registered through the Management API by making a `POST` request to the `/api/service`. The snippet below shows the `payload` request needed.
+
+```json
+{
+    "friendlyName": "{{serviceName}}",
+    "resourceGroup": "{{virtualMachineResourceGroup}}",
+    "subscriptionId": "{{subscriptionIdOfResourceGroup}}",
+    "name": "{{virtualMachineName}}",
+    "dns": "{{virtualMachineDnsName}}",
+    "isDefault": "{{serviceDefault}}"
+}
+```
+
+| Placeholder                            | Description                                                                         |
+|----------------------------------------|-------------------------------------------------------------------------------------|
+| serviceName                            | A meaningful name for the service to be configured/registered, e.g. `Test service`. |
+| virtualMachineResourceGroup            | The [resource group](readme.md#resource-groups) name where the virtual machine was created. |
+| subscriptionIdOfResourceGroup          | The subscription Id where the virtual machine resource group was created.           |
+| virtualMachineName                     | The name of the [virtual machine](bot_service_virtual_machine.md)                   |
+| serviceDefault                         | Indicates whether the service to be added is the default, set it to `true`.     |
+
+### Configure/register the service example
+You can use any HTTP client to configure/register the service to be used by the solution. In this example, the client used is `Postman`.
+
+Open `Postman` and create a new `POST` request pointing to the following endpoint: https://{{webAppUrl}}/api/service 
+
+| Placeholder                            | Description                                                                         |
+|----------------------------------------|-------------------------------------------------------------------------------------|
+| webAppUrl                              | This is the [Web App](web_app_and_app_service_plan.md) service in Azure URL where the Management API was deployed      |
+
+In the authorization tab, select `Bearer Token` for `Type` and add the authorization token in the corresponding `Token` input.
+
+![Postman authorization header](./images/postman_add_service_auth_header.png)
+
+To get the authorization token for the Management API resource you can follow the steps described in this [document](authorization_token.md).
+
+In the header tab, add (if it does not exist) a new key `Content-Type` with the value `application/json`.
+
+In the body tab select raw and complete by copying the following
+
+![Postman select body type](./images/postman_add_service_payload.png)
+
+Click on send to configure/register the service. 
+
+[← Back to How to Run the Solution in Azure](README.md#how-to-run-the-solution-in-azure)

docs/how-to-run-the-solution-in-azure/app_registrations.md

@@ -0,0 +1,167 @@
+# App Registrations
+
+## Getting Started
+
+To enable authentication in the solution, we must create the different **app registrations**, and apply some configuration settings between them in Azure Active Directory.
+
+We need to create app registrations for the following items:
+- BotService API.
+- BotService Client.
+- Management API.
+- Azure SDK Service Principal.
+
+To create the necessary app registrations, review the following Microsoft [documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#register-an-application) that will explain how to do it, and consider the following settings for each of them:
+
+- ***Name:*** Meaningful name.
+- ***Supported account types:*** Accounts in this organizational directory only (`your-organization` only - Single tenant).
+
+> **NOTE**: Please follow the steps to register the app registration and return to this document to apply the corresponding settings. 
+
+Once you've registered the app registration you must [add a client secret](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#add-a-client-secret), copy the value and save it together with the application client id in a secure place, we will need them for future steps.
+
+> **NOTE**: You'll need this secret later to configure the project. This key value will not be displayed again, nor retrievable by any other means, so record it as soon as it is visible from the Azure portal.
+
+## Authentication Setup
+
+With the **App Registrations** created in the previous steps, we must proceed we the setup of each of them. While doing so, take into consideration that there are some dependencies between some app registrations and the resources.
+
+- [How to Setup Bot Service API app registration](#how-to-setup-bot-service-api-app-registration)
+- [How to Setup Bot Service Client app registration](#how-to-setup-bot-service-client-app-registration)
+- [How to Setup Management API app registration](#how-to-setup-management-api-app-registration)
+
+### How to Setup Bot Service API app registration
+
+> **IMPORTANT**: it's necessary to have already created BotService API app registration.
+
+This section explains how to configure the BotService API app registration to enable Client Credential Authentication between APIs.
+
+#### Manifest
+
+In the BotService API Application Manifest editor, we need to change the value `accessTokenAcceptedVersion` field from null (which defaults to: 1) to 2 (for v2.0 tokens).
+
+![Manifest Bot Service API](./images/manifest_botservice_api.png)
+
+Finally, click on the **Save** button.
+
+#### App Roles
+
+> **NOTE**: Next, we will create a new Role, which will serve as a mechanism to demand authorization from the application.
+
+From the BotService API app registration view, go to the App roles option that is in the resource blade, click the **Create app role** button. Fill the following information with the values suggested.
+
+- ***Display name***: AccessAll.
+- ***Allowed member types***: Applications.
+- ***Values***: BotService.AccessAll.
+- ***Description***: Meaningful description e.g., Access to BotService API.
+
+![App Roles](./images/create_role_bot_service_api.png)
+
+Finally, click on the Apply button.
+
+#### Expose an API
+
+From the resource blade of the app registration view, go to the **Expose an API** option and click **Set** next to the Application ID URI to generate a URI that is unique for this app (in the form of api://{clientId}).
+
+### How to Setup Bot Service Client app registration
+
+> **IMPORTANT**: To complete this section it is necessary to have the role in the BotService API created.
+
+This section explains how to configure the BotService Client app registration to enable authentication.
+
+#### API permissions
+
+From the BotService Client app registration view, go to the **API permissions** option that is in the resource blade, click the **Add a permission** button and then ensure that the **APIs my organization** uses tab is selected. Search for the **BotService API** and click on the search result.
+
+![Search API permissions](./images/search_api_permissions.png)
+
+Then inside BotService select **AccessAll** and click on **Add permissions**.
+
+![Request API permissions.png](./images/request_api_permissions.png)
+
+> **NOTE**: If your user does not have the necessary permissions to enable the add-on permission. You must ask a user with the required permission to enable it.
+
+![Add permissions](./images/bot_service_client_enabled_permissions.png)
+
+### How to Setup Management API app registration
+
+**IMPORTANT**: it's necessary to have already created Management API app registration.
+
+This section explains how to configure the Management API app registration to enable authentication.
+
+#### Manifest
+
+In the Management API Application Manifest editor, you need to apply the same change in the manifest as you did for the previous app registration. Change the `accessTokenAcceptedVersion` field from null (which defaults to: 1) to 2 (for v2.0 tokens).
+
+#### API Graph permissions
+
+From the API app registration view, go to the **API permissions** option that is in the resource blade, click the **Add a permission** button and then ensure that the **Microsoft APIs** tab is selected.
+
+![API Graph permissions](./images/appi_graph_permissions.png)
+
+In the Commonly used Microsoft APIs section, click on **Microsoft Graph**. Then click in the **Delegated permissions** section and ensure that the right permissions are checked (`User.Read` and `offline_access`) and click the **Add permissions** button.
+
+![Add Graph permissions](./images/add_graph_permissions.png)
+
+#### App Roles
+
+> **NOTE**: Next, we will create a new Role, which will serve as a mechanism to demand authorization from other applications.
+
+From the Management API app registration view, go to the App roles option that is in the resource blade, click the **Create app role** button. Fill the following information with the values suggested.
+
+- ***Display name***: AccessAll.
+- ***Allowed member types***: Applications.
+- ***Values***: ManagementAPI.AccessAll.
+- ***Description***: Meaningful description e.g., Access to Management API.
+
+![App Roles](./images/create_role_management_api.png)
+
+Finally, click on the Apply button.
+
+#### Expose an API
+
+From the resource blade of the app registration view, go to the **Expose an API** option and click **Set** next to the Application ID URI to generate a URI that is unique for this app (in the form of api://{clientId}). Then click **Add scope**, complete the form following the parameters listed below, and finally click **Add scope** button.
+
+#### Parameters
+
+> **NOTE**: This `Scope` name is going to be used to develop/configure auth in the extension and they must match.
+
+- ***Scope name***: use `access_as_producer`.
+- ***Who can consent***: Admin and users.
+- Admin consent display name: enter a meaningful name. E.g.: `Access Broadcaster for Teams as producer`.
+- **Admin consent description**: enter a meaningful description.
+- **User consent display name**: enter a meaningful name. E.g.: `Access Broadcaster for Teams as producer`.
+- **User consent description**: enter a meaningful description.
+- **State**: Enabled
+
+![Add Scope](./images/management_api_add_scope.png)
+
+#### Manifest
+
+In order to enable RBAC through a security group, it is necessary to modify the app registration manifest to allow the application to include in the token all the security groups the user belongs to.
+
+From the resource blade of the app registration view, go to the **Manifest** option. We need to modify the manifest and add/modify the following key-values:
+
+```json
+"groupMembershipClaims": "SecurityGroup",
+"optionalClaims":{
+  "idToken": [
+    {
+      "name":"groups",
+      "source": null,
+      "essential": false,
+      "additionalProperties": [
+        "emit_as_roles"
+      ]
+    }
+  ],
+  "accessToken":[],
+  "saml2Token":[]
+}
+```
+![Security group claim](./images/management_api_optional_claims_of_manifest.png)
+
+Click the **Save** button to finish.
+
+> **NOTE**: The Azure SDK Service Principal app registration will be configured later after creating the resource group that will host the virtual machine.
+
+[← Back to How to Run the Solution in Azure](README.md#how-to-run-the-solution-in-azure)

docs/how-to-run-the-solution-in-azure/application_insights.md

@@ -0,0 +1,27 @@
+# Application Insights
+
+## Getting Started
+This instance will be used to log all the events happening in the solution.
+
+## Dependencies
+To continue with the Application Insights, the following dependencies need to be created:
+
+- [Resource Group](resource_group.md).
+
+### Settings.
+
+Create this Application Insights with the following settings:
+
+- ***Resource Group:*** Select the resource group created for the solution architecture.
+- ***Name:*** A meaningful name. 
+- ***Region:*** Same region as the rest of the resources. 
+- ***Resource mode:*** Classic.
+
+To create the Application Insights, please review the following Microsoft [documentation](https://docs.microsoft.com/en-us/azure/azure-monitor/app/create-workspace-resource).
+
+Once the **Application Insights** has been created, within the **Overview** option on the left panel we can view the Instrumentation key. The **instrumentation key** identifies the resource that you want to associate your telemetry data with. You will need to copy the **instrumentation key** and add it to your component settings.  
+
+![](./images/instrumentation_key_of_the_application_insights.png)
+
+
+[← Back to How to Run the Solution in Azure](README.md#how-to-run-the-solution-in-azure)

docs/how-to-run-the-solution-in-azure/authorization_token.md

@@ -0,0 +1,35 @@
+# Get Authorization Token
+
+## Introduction
+In order to make requests to the Management API deployed in Azure, you need to generate an authorization token. This token must be sent in the request by adding the `Authorization` header to it. 
+
+Following the steps in this document, you will be able to generate an authorization token using the Azure CLI.
+
+1. Download and install the Azure CLI, please review the Microsoft [documentation](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli-windows?tabs=azure-cli) to install it.
+
+1. After installing the Azure CLI, in a terminal window execute the command `az login` and enter your credentials in the browser displayed.
+
+1. In the [Azure Portal](https://portal.azure.com/), go to the app registration you want to obtain the authorization token in Azure AD, in this case, the app registration for the Management API. 
+
+1. On the left pane, click on **Expose an API**.
+
+1. Click on **Add a client application**.
+    ![Add client application](./images/app_registration_add_client_application.png)
+
+1. Add the application Id you want to add in the **Client ID**.
+    >**NOTE**: In this case, you need to authorize the `Azure CLI` application to allow to generate the authorization token from this application. The Id of this application is `04b07795-8ddb-461a-bbee-02f9e1bf7b46`.
+
+1. Select the **Authorized scopes**, and finally click on **Add application**.
+
+    ![Add client application blade](./images/app_registration_add_client_application_blade.png)
+
+1. Go to a terminal window and execute this command: `az account get-access-token --resource {{managementApiAppRegistrationId}}`. Replace the placeholder with the client Id of the app registration created for the [Management API](app_registrations.md).
+
+    ![Authorization token obtained from Azure CLI](./images/az_cli_authorization_token_output.png)
+
+1. Copy the `accessToken` value. 
+    >**NOTE**: This token is valid for one hour. After that, you will need to generate a new one. In that case, you only need to execute the last step in this document.
+
+[← Back to How to test the Management API](test_web_app.md#how-to-test-the-management-api)
+
+[← Back to How to test the Orchestrator Function](test_function_app.md#how-to-test-the-orchestrator-function)

docs/how-to-run-the-solution-in-azure/azure_sdk_service_principal.md

@@ -0,0 +1,17 @@
+# Azure SDK Service Principal
+
+## Getting Started
+
+The solution has components that require interaction with Azure resources using the Azure SDK. To allow this interaction, we need to create a Service Principal for the solution and assign it `Contributor` access to the specified Azure Resources. In this guide, we are going to explain how to assing the role to the app registration created in previous steps.
+
+## Dependencies
+To continue with the Azure SDK Service Principal documentation, the following dependencies need to be created:
+
+- [Resource Group](resource_group.md).
+
+### Assign Contributor Role
+For the time being, the solution needs to interact with the virtual machine where the Bot Service API is hosted (to turn on/turn off the virtual machine). To make this assignment, you must go to the **resource group** where the **virtual machine** was created and through **Access Control (IAM)** assign `Contributor` role to the application, please review the following Microsoft [documentation](https://docs.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal?tabs=current).
+
+![Assign Contributor Role](./images/assign_contributor_role.png)
+
+[← Back to How to Run the Solution in Azure](README.md#how-to-run-the-solution-in-azure)

docs/how-to-run-the-solution-in-azure/bot_service_virtual_machine.md

@@ -0,0 +1,137 @@
+# Bot Service Virtual Machine
+
+## Getting Started
+
+This document explains how to create the virtual machine where the Bot Service API is going to be hosted, and how to configure it.
+
+## Dependencies
+To continue with the Virtual Machine documentation, the following dependencies need to be created:
+
+- [Storage Account](storage_account.md).
+- [SSL Certificate](../prerequisites/readme.md).
+
+## Create the virtual machine in Azure
+
+To create the Virtual Machine, check the following document [Create a Windows Virtual Machine in the Azure Portal](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/quick-create-portal).
+
+While creating the virtual machine, consider the following settings:
+- ***Subscription:*** The azure subscription where you want to create the VM.
+- ***Resource Group:*** The resource group where you want to create the VM. We recommend creating a specific resource group for the VM, so you can easily identify the VM resources in case of resource deletion.
+- ***Virtual Machine Name:*** A meaningful name for the VM.
+- ***Image:*** Windows 10 Pro, Version 20H2.
+- ***Size:***
+    - Standard_F4s_v2 - 4 vcpus, 8 GiB memory. recommended for testing purpose.
+    - Standard_F8s_v2 - 8 vcpus, 16 GiB memory. Recommended for Production environments.
+- ***Username:*** A meaningful username.
+- ***Password:*** A meaningful password.
+
+### Network Security Group inbound rules
+
+Once the virtual machine is created, we must add inbound rules in the network security group.
+
+**Inbound rules**
+
+| Name            | Port      | Protocol | Purpose                                                                 |
+|-----------------|-----------|----------|-------------------------------------------------------------------------|
+| SRT             | 8880-9000 | UDP      | Used for SRT protocol for media extraction & injection.                 |
+| HTTPS           | 443       | TCP      | Allows communication from the main API.                                 |
+| MediaPlatform   | 8445      | TCP      | Used to establish communication between the bot and the media platform. |
+| RTMP            | 1935-1936      | TCP      | Used to extract & inject RTMP content.                                          |
+| RTMPS           | 2935-2936      | TCP      | Used to extract & inject RTMPS content.                                                 |
+
+### Configure the virtual machine
+Before starting using the virtual machine, we must install the applications listed below.
+
+> **IMPORTANT**: The disk D:\ is a temporary disk (files are deleted after shutdown/restart of the virtual machine) so you must install all the applications in C:\.
+
+#### Gstreamer
+Download the GStreamer installer from this [link](https://gstreamer.freedesktop.org/data/pkg/windows/1.18.4/mingw/gstreamer-1.0-mingw-x86_64-1.18.4.msi). Once you have downloaded the installer and started the installation process, choose the custom installation and make sure that all modules have been selected and the installation path is in C:\.
+
+> **IMPORTANT**: Remember to select all GStreamer modules/plugins while installing GStreamer as a custom installation.
+
+After GStreamer installation, add the GStreamer bin folder path to the path environment variable.
+
+#### VCRedist
+Download [VCRedist](https://aka.ms/vs/16/release/vc_redist.x64.exe) and install it.
+
+#### NGINX
+Follow this guide [How to Install and configure NGINX with RTMP module on Windows](install_and_configure_nginx_with_rtmp_module_on_windows.md) to install and configure NGINX with RTMP module on windows, and configure it as a Windows service.
+
+### Bot Service
+At the moment,  there isn't automated deployment for the Bot Service API so, you need to use Visual Studio to publish the BotService project into a local folder.
+
+Go to the Solution Explorer, right-click on BotService project and click **Publish**.
+
+![Publish Bot Service](./images/publish_bot_service.png)
+
+In the publish tab, configure the Target Location, and edit the following settings:
+- ***Configuration:*** Release
+- ***Target Framework:*** net472
+- ***Target Runtime:*** win7-x64
+
+![Configuration to Publish Bot Service](./images/configuration_to_publish_bot_service.png)
+
+Check the configuration and to finish publishing, press the **Save** button.
+![Configuration to Publish Bot Service](./images/save_publish_from_bot_service.png)
+
+After that, we can publish the project, and copy the files into the virtual machine. Later, we will explain how to run it from the command line or as a Windows Service.
+
+### Environment variables
+In order to run the bot, we need to configure some environment variables that the bot will read in order to get access to its configuration settings and certificate.
+
+> **IMPORTANT** Before performing these steps, the storage account with the bot configurations must be already created to set the environment's variables.
+
+![Set Environment Variables](./images/set_environment_variables.png)
+
+![Set Systema Variables](./images/set_system_variables.png)
+
+| **Placer**                | **Description**                                                      |
+|---------------------------|----------------------------------------------------------------------|
+| storage account           | Name of the [Storage account](app_registrations.md) where the files are being stored.    |
+| blob container            | Name the container of [Storage account](app_registrations.md).                           |
+| blob sas query            | SAS key to get access to the container files of [Storage account](app_registrations.md). |
+| settings json file name   | Name of the bot app settings file uploaded into the config container in the [Storage account](app_registrations.md).  |
+| certificate pfx file name | Name of `.pfx` [wilcard certificate](../prerequisites/readme.md) for the domain.  |
+
+
+> **NOTE**: The `BLOB_SAS_QUERY` must include the '?' at the beginning. This token has an expiration date, be aware of this date to renew the access token.
+
+### Running the bot
+We have two alternatives to run the bot, from the command line and as a Windows Service. The first alternative is used when we want to see the logs in the terminal. There are some GStreamer and external libraries stdout/stderr we can't capture nor log them in application insights. The second alternative is used to run the Bot Service authomatically when the VM starts.
+
+> **NOTE**: The first time we configure the environment, we recommend running it from the command line so windows prompts the firewall rule and we can accept and enable it.
+
+#### From command line
+In this scenario, you can run the Bot Service by executing the command `.\BotService.exe --console` in a terminal window from the path where the Bot Service is located.
+
+If you want to override the environment settings, 
+you can create a Powershell script in the root folder of the bot. Below there is a sample of the script to override the default environment variables with other values if necessary.
+
+```bash
+$env:BLOB_SAS_QUERY = '?{{sasQuery}}'
+$env:STORAGE_ACCOUNT = '{{storageAccountName}}'
+$env:BLOB_CONTAINER = '{{containerName}}'
+$env:APP_SETTINGS_FILE_NAME = '{{envFileName}}'
+$env:CERTIFICATE_FILE_NAME = '{{certFileName}}'
+.\BotService.exe --console
+```
+
+> **NOTE**: Enable remote signed script for Powershell `set-executionpolicy remotesigned`.
+
+#### As a Windows Service
+To run the bot every time the virtual machine is turned on, we configure it as a Windows Service. Before configuring it, we must validate that the group **ALL APPLICATION PACKAGES** has special permissions in the bot folder (right-click in the bot folder, click on **properties**, select the **security** tab). If the group doesn't have permissions, we must add it by clicking on **Advance** → **Add** → **Select a Principal**.
+
+![As a Windows Service](./images/configure_windows_service.png)
+![Permission entry bot service](./images/permission_entry_bot_service.png)
+
+Finally, we must run the following Powershell command:
+
+```bash
+New-Service -Name "Bot-Service" -BinaryPathName '"C:\{bot-service-path}\BotService.exe"'
+```
+
+After completing these steps, we must restart the virtual machine or start the Bot Service from the Windows Services app. 
+
+>**NOTE**: Before running the BotServie for the first time, we must complete the settings uploaded into the [Storage Account](storage_account.md#environment-json-file-settings-example). 
+
+[← Back to How to Run the Solution in Azure](README.md#how-to-run-the-solution-in-azure)

docs/how-to-run-the-solution-in-azure/configure_event_grid.md

@@ -0,0 +1,53 @@
+# How to configure Event Grid
+
+## Introduction
+
+To keep the state of the bot service virtual machine consistent is Cosmos DB, we
+we must configure an event grid subscription to execute an Azure Function that updates its register in Cosmos DB, every time that it is being started/stopped from an external event, e.g.: A user starts/stops the virtual machine from Azure Portal or has scheduled auto-shutdown.
+
+## Dependencies
+To continue with the Virtual Event Grid documentation, the following dependencies need to be created:
+
+- [Cosmos DB](cosmos_db.md).
+- [BotOrchestrator deployed](deploy_function_app.md).
+
+## Getting Started
+
+To start configuring Event Grid events, we must create an Event Grid Topic resource.
+
+1. Sign in to [Azure portal](https://portal.azure.com/).
+1. In the search bar at the topic, type **Event Grid Topics**, and then select E**vent Grid Topics** from the drop-down list.  
+![Event Grid search](./images/event_grid_search.png)
+1. On the **Event Grid Topics** page, select **+ Add** on the toolbar.  
+![](./images/add_event_grid_topic_button.png)
+1. On the **Create Topic** page, complete the requested information:
+    > **NOTE**: We recommend creating the topic in the same resource group where we are going to subscribe to an event (the resource group of the virtual machine) and the same location where the virtual machine was created.
+    - ***Subscription:*** The Azure subscription where you want to create the topic.
+    - ***Resource Group:*** The resource group where you want to create the topic.
+    - ***Name:*** A meaningful name.
+    - ***Location:*** The Azure location of the resource.
+1. Select **Review + create** at the bottom of the page.
+![Review + create](./images/create_custom_topic.png)
+1. To finish, check the information loaded in the **Review + create** tab, and click on the **Create** button.
+![Create](./images/review-create-page.png)
+
+
+After creating the topic, to configure an Azure function as an event handler for Event grid events, we must go to the resource group where we created the virtual machine, click on the **Events** option located in the resource blade, and then click on **Event Subscription** button.
+
+![Create event subscription](./images/create_new_event_subscription.png)
+
+
+While creating the Event Subscription, complete the requested information and click on Create button:
+
+- ***Name:*** A meaningful name.
+- ***Event Schema:*** Event Grid Schema.
+- ***System Topic Name:*** The name of the topic we created before.
+- ***Filter to Event Types:*** Select Resource Action types.
+- ***Endpoint Types:*** Azure function.
+- ***Endpoint:*** Select the Azure Function that will handle the Event Grid events. By default, it is created in the environment resource group, under the function app with the name virtual-machine-event-grid-handler.
+
+![Event subscription details](./images/details_of_the_new_event_subscription.png)
+
+![Event grid select_azure_function](./images/event_grid_select_azure_function.png)
+
+[← Back to Running the Solution in Azure](README.md#how-to-run-the-solution-in-azure)

docs/how-to-run-the-solution-in-azure/cosmos_db.md

@@ -0,0 +1,74 @@
+# Cosmos DB Database
+
+## Getting Started
+
+We use **Azure Cosmos DB** database store the `Broadcast Development Kit` data. In this document, we will explain you step by step how to create the Azure resource and how to configure it.
+
+
+To create the Azure Cosmos DB, please review the following Microsoft [documentation](https://docs.microsoft.com/en-us/azure/cosmos-db/create-cosmosdb-resources-portal#create-an-azure-cosmos-db-account).
+
+## Dependencies
+To continue with the Cosmos DB documentation, the following dependencies need to be created:
+
+- [Resource Group](resource_group.md).
+
+### Settings:
+
+- ***Select API option:*** choose Core (SQL).
+- ***Resource Group:*** Select the [resource group](resource_group.md) created for the solution architecture.
+- ***Account Name***: a meaningful name. 
+- ***Location***: same region as the rest of the resources. 
+- ***Capacity mode***: Provisioned throughput. 
+- ***Apply Free Tier Discount***: Apply only if there is no other Cosmos DB using it in the subscription.
+
+Leave the rest of the settings as-is.
+
+> **NOTE:**  The backend components already create the database and containers when they run for the first time. However, the containers aren't going to havea shared throughput. To save cost, we recommend you to continue with this guide and create database manually.
+
+Once the database is created, browse to the **Data Explorer** in the left panel of the account configuration and create a new database with the following settings: 
+
+- Database Id: A meaningful name. 
+- Throughput: Manual – 400 RU/s. 
+    > Note: To keep the costs down, you are setting the RU to the lowest amount possible.
+
+Click on **OK** button to create the database.
+
+After the database is created, it is necessary to add all the containers needed by the solution. The following list shows the name of the containers to be created and the corresponding partition key name:
+
+- ***Call***
+    - Partition Key: /id
+- ***ParticipantStream***
+    - Partition Key: /id
+- ***Service***
+    - Partition Key: /id
+- ***Stream***
+    - Partition Key: /id
+
+To create those containers, please follow the next steps:
+
+1. In the `Data explorer` view for Cosmos DB in the Azure Portal, select `New Container`.
+1. Fill the `New Container` blade displayed with the following values:
+    - ***Database id***: Check use existing and select the one created in the previous step.
+    - ***Container id***: Write the name of the container (e.g. *Call*).
+    - ***Partition key***: Write the name of the partition key (e.g. for Call container the partition key name is /id).
+    - ***Provision dedicated throughput for this container***: Keep unchecked to share the database throughput between all the containers created.
+1. Click **OK** button to create the container.
+
+The images below show the steps from the Azure Portal.
+
+#### Create `New Container` button.
+
+![Add new container](./images/cosmos_db_create_new_container.png)
+
+#### Create `New Container` blade displayed.
+
+![Fill the data to create the container](./images/cosmos_db_create_new_container_blade.png)
+
+>NOTE: The steps described above can be done through the Microsoft Azure Storage explorer. 
+
+
+Finally, go to the resource blade on the left, go to the setting section click on Keys. Copy and save the `URI` and `PRIMARY KEY` from the values displayed. Those values are required along with the database name to complete the configuration of the Bot Service, Bot Orchestrator and Management API.
+
+![Uri and primary key values to copy](./images/cosmos_db_key_and_connection_string.png)
+
+[← Back to How to Run the Solution in Azure](README.md#how-to-run-the-solution-in-azure)

docs/how-to-run-the-solution-in-azure/deploy_function_app.md

@@ -0,0 +1,56 @@
+# Deploy the Function App into the Azure Function App Service.
+
+Once the Function App with the corresponding App service plan was successful created, we can deploy the solution build into it. 
+
+## Dependencies
+To continue with the Deploy the Function App into the Azure Function App Service documentation, the following dependencies need to be created:
+
+- [Function App](function_app_and_app_service_plan.md).
+
+To deploy the Function App into the Azure Function App Service created we can follow this steps:
+1. Open the solution in **Visual Studio**.
+1. In Solution Explorer, right-click in the project `BotOrchestrator` node and choose **Publish**.
+1. In **Publish**, select **Azure** and then **Next**.  
+![Select Azure](./images/deploy_function_app_select_azure.png)
+1. Choose in the **specific destination** the option Azure App Service (Windows).  
+![Select specific destination](./images/deploy_function_app_select_specific_destination.png)
+1. Select your subscription and in the **Function Apps** panel, select the Function App that was created from the Azure Portal, and click **Finish**.  
+![Select Function App Created](./images/deploy_function_app_select_function_app_created.png)
+1. Then in the **Service Dependencies** section, in the **Storage Account**, select the option **Configure**.
+![imagen](images/deploy_function_app_sa_config.png)
+1. Select your **Subscription** and the [Storage Account](storage_account.md) created in the previous steps, then press the **Next** button.
+![Configure Storage Account](images/deploy_function_app_sa_select.png)
+1. Then check the **Azure App Settings** option and click on the **Next** button.
+![Check Azure App Settings](images/deploy_function_app_sa_check.png)
+1. In this section uncheck the **three** Azure Storage options and click on the **Finish** button.
+![Uncheck thethre Azure Storage options](images/deploy_function_app_sa_uncheck.png)
+1. To finish, on the **Publish** page, select **Publish**. Visual Studio builds, packages, and publishes the app to Azure.
+
+## Configure app settings
+After deploying the **Function App**, it is necessary to set the configuration parameters. These are carried out by following the steps below:
+
+1. In the [Azure portal](http://portal.azure.com/), search for and select Function App, and then select your app.  
+
+![Application settings](./images/function_app_search.png)
+1. Select in the app's left menu, select **Configuration** > **Application settings**.  
+
+![New application setting](./images/function_app_configuration_application_settings.png)
+1. To add a setting in the portal, select **New application setting** and add the new key-value pair.  
+It is necessary to create the following application settings:
+
+    | Name                                                        | Value                                                                   |
+    |-------------------------------------------------------------|-------------------------------------------------------------------------|
+    | AzServicePrincipalConfiguration:ApplicationClientId         | Client Id of the [Azure SDK Service Principal](azure_sdk_service_principal.md) app registration.              |
+    | AzServicePrincipalConfiguration:ApplicationClientSecret     | Client secret of the [Azure SDK Service Principal](azure_sdk_service_principal.md) app registration.          |
+    | AzServicePrincipalConfiguration:SubscriptionId              | Subscription Id of the [Azure SDK Service Principal](azure_sdk_service_principal.md) app registration.        |
+    | AzServicePrincipalConfiguration:TenantId                    | Tenant Id of [Azure SDK Service Principal](azure_sdk_service_principal.md) app registration.                  |
+    | AZURE_FUNCTIONS_ENVIRONMENT                                 | Development or Production                                               |
+    | BuildVersion                                                | Version number deployed e.g. 0.0.0-test                                 |
+    | CosmosDbConfiguration:DatabaseName                          | Database name of the [Cosmos DB](cosmos_db.md) created.                           |
+    | CosmosDbConfiguration:EndpointUrl                           | Endpoint URL of the [Cosmos DB](cosmos_db.md) created.                            |
+    | CosmosDbConfiguration:PrimaryKey                            | Primary key of the [Cosmos DB](cosmos_db.md) created.                             |
+
+1. Finally, click on the **Save** button.  
+![Save new application settings](./images/function_app_save_new_application_settings.png)
+
+[← Back to How to Run the Solution in Azure](README.md#how-to-run-the-solution-in-azure)

docs/how-to-run-the-solution-in-azure/deploy_web_app.md

@@ -0,0 +1,66 @@
+# Deploy the Web App into the Azure App Service.
+
+Once the Web App with the corresponding Azure App service plan was successful created, we can deploy the solution build into it. 
+
+## Dependencies
+To continue with the Deploy the Web App into the Azure App Service documentation, the following dependencies need to be created:
+
+- [Web App](web_app_and_app_service_plan.md).
+
+To deploy the Web App into the Web Azure App Service created we can follow this steps:
+1. Open the solution in **Visual Studio**.
+1. In Solution Explorer, right-click in the project `ManagementApi` node and choose **Publish**.
+1. In **Publish**, select **Azure** and then **Next**.  
+![Select Azure](./images/deploy_web_app_select_azure.png)
+1. Choose in the **specific destination** the option Azure App Service (Windows).  
+![Select specific destination](./images/deploy_web_app_select_specific_destination.png)
+1. Select your subscription and in the **Web Apps** panel, select the Web App that was created from the Azure Portal, and click **Finish**.  
+![Select Web App Created](./images/deploy_web_app_select_web_app_created.png)
+1. In the **Publish** page, select **Publish**. Visual Studio builds, packages, and publishes the app to Azure, and then launches the app in the default browser.
+
+## Configure app settings
+After deploying the **Web App**, it is necessary to set the configuration parameters. These are carried out by following the steps below:
+
+1. In the [Azure portal](http://portal.azure.com/), search for and select App Services, and then select your app.  
+![Application settings](./images/web_app_search.png)
+1. Select in the app's left menu, select **Configuration** > **Application settings**.  
+![New application setting](./images/function_app_configuration_application_settings.png)
+1. To add a setting in the portal, select **New application setting** and add the new key-value pair.  
+It is necessary to create the following application settings:
+
+    | Name                                                                 | Value                                                                  |
+    |----------------------------------------------------------------------|------------------------------------------------------------------------|
+    | APPINSIGHTS_INSTRUMENTATIONKEY                                       | Key of the [Application Insights](application_insights.md) resource created. |
+    | APPINSIGHTS_PROFILERFEATURE_VERSION                                  | disabled                                                               |
+    | APPINSIGHTS_SNAPSHOTFEATURE_VERSION                                  | disabled                                                               |
+    | ApplicationInsightsAgent_EXTENSION_VERSION                           | ~2                                                                     |
+    | DiagnosticServices_EXTENSION_VERSION                                 | disabled                                                               |
+    | InstrumentationEngine_EXTENSION_VERSION                              | disabled                                                               |
+    | Logging:LogLevel:Default                                             | Information                                                            |
+    | Settings:AzServicePrincipalConfiguration:ApplicationClientId         | Client Id of the [Azure SDK Service Principal](azure_sdk_service_principal.md) app registration.             |
+    | Settings:AzServicePrincipalConfiguration:ApplicationClientSecret     | Client secret of the [Azure SDK Service Principal](azure_sdk_service_principal.md) app registration.         |
+    | Settings:AzServicePrincipalConfiguration:SubscriptionId              | Subscription Id of the [Azure SDK Service Principal](azure_sdk_service_principal.md) app registration.       |
+    | Settings:AzServicePrincipalConfiguration:TenantId                    | Tenant Id of [Azure SDK Service Principal](azure_sdk_service_principal.md) app registration.                 |
+    | ASPNETCORE_ENVIRONMENT                                               | Development or Production                                                           |
+    | Settings:AzureAdConfiguration:ClientId                                | Id of the [Management API](app_registration.md) app registration created in Azure  AD.                                                  |
+    | Settings:AzureAdConfiguration:GroupId                                | Id of the [Security Group](security_group.md) created in Azure  AD.                                                  |
+    | Settings:AzureAdConfiguration:Instance                               | https://login.microsoftonline.com/                                     |
+    | Settings:AzureAdConfiguration:TenantId                               | Tenant Id of Azure AD.                                                 |
+    | Settings:BotServiceAuthenticationConfiguration:BotServiceApiClientId | Client Id of the [Bot Service API](app_registrations.md) app registration.                     |
+    | Settings:BotServiceAuthenticationConfiguration:ClientId              | Client Id of the [Bot Service Client](app_registrations.md) app registration.                  |
+    | Settings:BotServiceAuthenticationConfiguration:ClientSecret          | Client secret of the [Bot Service Client](app_registrations.md) app registration.              |
+    | Settings:BuildVersion                                                | verision deployed e.g. 0.0.1-test                                      |
+    | Settings:CosmosDbConfiguration:DatabaseName                          | Database name of the [Cosmos DB](cosmos_db.md) created.                                |
+    | Settings:CosmosDbConfiguration:EndpointUrl                           | Endpoint URL of the [Cosmos DB](cosmos_db.md) created.                                 |
+    | Settings:CosmosDbConfiguration:PrimaryKey                            | Primary key of the [Cosmos DB](cosmos_db.md) created.                                  |
+    | Settings:GraphClientConfiguration:ClientId                           | Client Id of the [Azure Bot](../prerequisites/azure_bot.md) app registration.                           |
+    | Settings:GraphClientConfiguration:ClientSecret                       | Client secret of the [Azure Bot](../prerequisites/azure_bot.md) app registration.                       |
+    | Settings:GraphClientConfiguration:TenantId                           | Tenant  Id of the [Azure Bot](../prerequisites/azure_bot.md) app registration.                          |
+    | Settings:StorageConfiguration:ConnectionString                       | Connection string of the [Storage account](storage_account.md) created where the config is stored.   |
+    | SnapshotDebugger_EXTENSION_VERSION                                   | disabled                                                               |
+    | XDT_MicrosoftApplicationInsights_BaseExtensions                      | disabled                                                               |
+    | XDT_MicrosoftApplicationInsights_Mode                                | recommended                                                            |
+1. Finally, click on the **Save** button.  
+![Save new application settings](./images/web_app_save_new_application_settings.png)
+
+[← Back to How to Run the Solution in Azure](README.md#how-to-run-the-solution-in-azure)

docs/how-to-run-the-solution-in-azure/function_app_and_app_service_plan.md

@@ -0,0 +1,33 @@
+# Function App
+
+## Introduction
+A Function App for it must be created to host the Azure VM Management. This document is intend to show, how to create a Function App in the resource group created for the architecture solution.
+
+## Dependencies
+To create the Function App service needed to deploy the Orchestrator function, the following resources must be already created:
+
+- [App Service Plan](service_plan.md). 
+- [Azure Storage Account](storage_account.md).
+- [Application Insights](application_insights.md). 
+
+### Settings
+Fill the fields in the creation wizard with the following information:
+
+- ***Basic:***
+    - ***Resource Group:*** Select the [resource group](readme.md#architecture-resource-group) created for the solution architecture.
+    - ***Name:*** A meaningful name.
+    - ***Publish:*** Code.
+    - ***Runtime stack:*** .NET Core 3.1 (LTS).
+    - ***Region:*** Same region as the rest of the resources.
+- ***Hosting:*** 
+    - ***Storage account:*** Select the first [Storage Account](storage_account.md) that was created in the previous steps. 
+    - ***Operative system:*** Windows. 
+    - ***Plan:***
+        - ***Plan type:*** App Service plan.
+        - ***Windows Plan:*** Select the [App Service plan](service_plan.md) created in the previous steps. 
+- ***Monitoring:*** Enable [application insights](application_insights.md) and select the instance that was created in a previous step.
+
+To create the Function App and App Service Plan, please review the following Microsoft [documentation](https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-function-app-portal#create-a-function-app).
+
+
+[← Back to How to Run the Solution in Azure](README.md#how-to-run-the-solution-in-azure)

docs/how-to-run-the-solution-in-azure/resource_group.md

@@ -0,0 +1,12 @@
+# Resource Group
+
+## Getting Started
+
+To organize the different components of the solution we recommend creating two **resource groups** in your Azure subscription, both in the same **region**(e.g., **West US 2**).
+
+- **resource-group-name-bot** – This  group  will  contain  the  rest  of  the resources related to the APIs, functions, database, and web UI used to operate the solution.
+- **resource-group-name-bot-vm** – This group will be used to contain the resources  related  to  the  virtual  machine  that  will  host  the  core components of the application in Azure
+
+To create the resource groups, check the [Create resource groups](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal#create-resource-groups) documentation.
+
+[← Back to How to Run the Solution in Azure](README.md#how-to-run-the-solution-in-azure)

docs/how-to-run-the-solution-in-azure/security_group.md

@@ -0,0 +1,25 @@
+# Security Group
+
+## Getting Started
+
+The Security Group will be used to grant access and permissions to predefined users to the application. 
+
+To create the **Security Group** and **add members**, review the following Microsoft [documentation](https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/active-directory-groups-create-azure-portal#create-a-basic-group-and-add-members).
+
+### Settings:
+
+- ***GroupType:*** Select the group type **Security**. 
+- ***Group name:*** A meaningful name. 
+- ***Group description:*** A meaningful description (optional).
+- ***Membership type:*** Select **Assigned** membership for the group.
+
+> **NOTE:** You will need the `Group Id` later to configure the project, so register it as soon as it is visible from the Azure portal.
+
+## Add Member to the Security Group
+Once the **Security Group** has been created, it is necessary to add the members of the group that will be able to operate the solution. To add members, it is suggested to carry out the following steps:
+1. Enter the **Security Group** created and select the *Members* option on the left panel.
+![Add Members](images/security_group_add_members.png)
+1. Then click on the **+ Add members** button and start searching for members to add to your group, and click on the **Select** button to add them.
+![](images/security_group_select_members.png)
+
+[← Back to How to Run the Solution in Azure](README.md#how-to-run-the-solution-in-azure)

docs/how-to-run-the-solution-in-azure/service_plan.md

@@ -0,0 +1,39 @@
+# App Service Plan
+
+## Introduction
+An App Service Plan for it must be created to define the set of processing resources for the Apps services to execute.
+
+## Dependencies
+To continue with the App Service Plan, the following dependencies need to be created:
+
+- [Resource Group](resource_group.md).
+
+### Settings
+Fill the fields in the creation wizard with the following information:
+
+- ***Resource Group:*** Select the [resource group](readme.md#architecture-resource-group) created for the solution architecture.
+- ***Name:*** A meaningful name.
+- ***Operating System:*** Windows.
+- ***Region:*** Same region as the rest of the resources.
+- ***Pricing Tier***
+    - ***Sku and size:*** Shared D1.
+    > **NOTE**: This tier (Shared D1) is to reduce costs during the test. It can be increased if needed.
+
+### Create App Service Plan in Azure.
+1. In the [Azure Portal](https://portal.azure.com/), click **Create a resource**, and in the search bar enter **application service plan**. Then click on **Create** button.
+
+    ![Search application service plan](images/service_plan_search.png)
+    
+1. Select the subscription and complete the fields following the indications in the previous section. Then in the **Pricing Tier** section click on **Change size**.
+
+    ![Complete the fields](images/service_plan_information.png)
+
+1. Next, in the **Recommended pricing tiers** panel, select the **Dev/Test** tab, then select the **D1** tier, and click on **Apply**.
+
+    ![Recommended pricing tiers](images/service_plan_select_tier.png)
+
+1. Then press the tab **Create** button to finish with the creation.
+
+    ![Create](images/service_plan_create.png)
+
+[← Back to How to Run the Solution in Azure](README.md#how-to-run-the-solution-in-azure)