Merge pull request #14 from microsoft/docs/update-deploy-and-config-instructions

Update deploy and configuration instructions to include other options

docs/common/install_and_configure_nginx_with_rtmp_module_on_windows.md

@@ -16,7 +16,7 @@ Download as a zip NGINX with RTMP module from the following [GitHub repository](
 |*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)
+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)|
 |:--:|

docs/common/install_domain_certificate.md

@@ -0,0 +1,43 @@
+# Manual installation of your domain certificate
+
+## About
+This document explains how to manually install your domain certificate in your virtual machine or local environment. 
+
+## Installing the certificate
+Copy the [pfx certificate mentioned in the prerequisites](../prerequisites/README.md) to your virtual machine or local environment and double click on it to run the certificate import wizard.
+
+On the first screen, select `Local machine` as the Store Location and click `Next` (Windows may ask for administrator rights).
+
+|![Import Certificate](images/import_certificate.png)|
+|:--:|
+|*Certificate Import Wizard*|
+
+Click `Next` on the File to import step.
+
+In the Privacy Key Protection step, the wizard will ask for the password to read the certificate's private key, complete it and leave the rest of the settings as-is and click next.
+
+|![Import Certificate](images/certificate_password.png)|
+|:--:|
+|*Complete the password to read the certificate*|
+
+Finally, in the Certificate Store selection, click on `Browse` and select `Personal`. Then continue with the rest of the wizard.
+
+## Obtaining the certificate thumbprint
+
+Later it will be necessary to obtain the certificate thumbprint to complete the botservice configuration. To obtain it press Win+R keys, complete the input with `certlm.msc` and press `Ok`.
+
+|![Run Certificate](images/run_certificate.png)|
+|:--:|
+|*Complete the input and press Ok*|
+
+Navigate to `Certificates - Local Computer\Personal\Certificates`, search for the name of the certificate and open it (Either by double clicking or left click and open).
+
+|![Run Certificate](images/certificate_personal.png)|
+|:--:|
+|*Search the certificate and open it*|
+
+Go to details tab and search for Thumbprint field, select it, and copy its value.
+
+|![Run Certificate](images/certificate_thumbprint.png)|
+|:--:|
+|*Copy the thumbprint of the certificate*|

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

@@ -16,12 +16,14 @@ This document describes the resources that must be created and configured to run
         - [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).
+        - [App Service Plan](service_plan.md).
-        - [Function App and App service plan](function_app_and_app_service_plan.md).
+        - [Web App](web_app_and_app_service_plan.md).
+        - [Function App](function_app_and_app_service_plan.md).
     - Virtual Machine resource group:
-        - [Virtual Machine](bot_service_virtual_machine.md).
+        - [Virtual Machine](virtual_machine.md).
         - [Event Grid](configure_event_grid.md).
 - Components Deployment:
+    - [Deploy the Bot Service into the Virtual Machine](deploy_bot_service.md).
     - [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:
@@ -29,6 +31,12 @@ This document describes the resources that must be created and configured to run
     - [How to test the Management API](test_web_app.md)
     - [How to test the Orchestrator Function](test_function_app.md)
 
+## General prerequisites
+
+Before deploying the solution in Azure, please make sure you have the all the prerequisites listed in [Prerequisites](..\prerequisites\README.md).
+
+Also, if you haven't already, make sure you have setup your [Azure Bot](..\prerequisites\azure_bot.md) too.
+
 ## 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.  
 
@@ -65,5 +73,5 @@ The following resources form the core part of the solution, which is charge of c
 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).
+- [Virtual Machine](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

@@ -6,13 +6,20 @@ In order to start using the Azure environment once all the components have been
 ## Dependencies
 To configure/register the service, the following dependencies need to be created:
 
-- [Management API ](deploy_web_app.md).
+- [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
+## Configure/Register the service
+There are two approaches you can follow to configure/register the service in the database:
+1. **Sending a request to the Management API**. This is the recommended approach, but take into account that the API is secured through Azure AD and you will need to generate an access token to use this endpoint.
+2. **Manually adding the service in the database**. This approach is easier, but it can be error prone.
+
+Below you can find both approaches.
+
+### Configure/Register using the API
 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
@@ -29,12 +36,12 @@ The service is configured/registered through the Management API by making a `POS
 | 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. |
+| 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)                   |
+| virtualMachineName                     | The name of the [virtual machine](virtual_machine.md)                               |
-| serviceDefault                         | Indicates whether the service to be added is the default, set it to `true`.     |
+| serviceDefault                         | Indicates whether the service to be added is the default, set it to `true`.         |
 
-### Configure/register the service example
+#### Example of how to use this endpoint
 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 
@@ -57,4 +64,44 @@ In the body tab select raw and complete by copying the following
 
 Click on send to configure/register the service. 
 
+### Configure/Register in the database
+With the virtual machine running, go to your Cosmos DB database, locate the `Service` container and create a new entry with the following information. Then click `Save` to persist the changes.
+
+```json
+{
+    "CallId": null,
+    "Name": "{{service-name}}",
+    "State": 1,
+    "CreatedAt": "2021-08-01T00:00:00+00:00",
+    "Infrastructure": {
+        "VirtualMachineName": "{{vm-name}}",
+        "ResourceGroup": "{{resource-group}}",
+        "SubscriptionId": "{{subscription}}",
+        "Id": "{{infrastructure-id}}",
+        "PowerState": "PowerState/running",
+        "IpAddress": null,
+        "Dns": "{{dns-name}}",
+        "ProvisioningDetails": {
+            "Message": "Service provisioned.",
+            "State": {
+                "Id": 1,
+                "Name": "Provisioned"
+            }
+        }
+    },
+    "id": "00000000-0000-0000-0000-000000000000"
+}
+```
+
+| Placeholder           | Description                                                           |
+|-----------------------|-----------------------------------------------------------------------|
+| serviceName           | A custom name for this service instance. E.g. "Default Service".      |
+| vm-name               | The name of the virtual machine you created in Azure.                 |
+| resource-group        | The name of the Azure resource group containing the virtual machine.  |
+| subscription          | The ID (GUID) of your Azure subscription.                             |
+| infrastructure-id     | This ID is constructed with the previous placeholders using the following format. **The entire string needs to be in lowercase**. `/subscriptions/{{subscription}}/resourcegroups/{{resource-group}}/providers/microsoft.compute/virtualmachines/{{vm-name}}`.
+| dns-name              | The domain name you configured for the virtual machine.               |
+
+> Note: In the current implementation, the ID `00000000-0000-0000-0000-000000000000` is the ID of the bot service. Keep that ID in the json object as-is.
+
 [← 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_bot_service.md

@@ -0,0 +1,74 @@
+# Deploy the Bot Service
+
+This document describes how to deploy and install the Bot Service into a pre-configured virtual machine.
+
+## Dependencies
+
+Before following this document, these dependencies need to be created and configured:
+- [Virtual Machine](virtual_machine.md).
+
+## Deploying the service
+
+At the moment, there isn't automated deployment for the Bot Service so you need to manually copy and install the compiled version of the Bot Service in your virtual machine. To do this you can use one of the released versions of the Bot Service or compile the code manually in Visual Studio.
+
+### Using a released version
+To deploy a released version of the solution go to the [Releases](https://github.com/microsoft/Broadcast-Development-Kit/releases) page and download the Zip file for the version of the Bot Service that you want to use.
+
+Then copy the Zip file to your VM and un-zip the files into the folder where you want to install you Bot Service.
+
+### Building from the source code
+Open the solution in Visual Studio. Then, 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 (a folder in your local machine), 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 from the Target Location folder into the virtual machine. Later, we will explain how to run it from the command line or as a Windows Service.
+
+## 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**: You might need to enable remote signed scripts in Powershell using the command `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/deploy_function_app.md

@@ -7,6 +7,16 @@ To continue with the Deploy the Function App into the Azure Function App Service
 
 - [Function App](function_app_and_app_service_plan.md).
 
+## Deploying a released version
+To deploy a released version of the solution go to the [Releases](https://github.com/microsoft/Broadcast-Development-Kit/releases) page and download the Zip file for the version of the Bot Orchestrator you want to deploy.
+
+Then, using **Azure CLI** (either locally or in the Azure Portal), run the following command to deploy the Zip file:
+
+```
+az functionapp deployment source config-zip -g <resource_group> -n <app_name> --src <zip_file_path>
+```
+
+## Building and deploying from the source code
 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**.

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

@@ -7,6 +7,16 @@ To continue with the Deploy the Web App into the Azure App Service documentation
 
 - [Web App](web_app_and_app_service_plan.md).
 
+## Deploying a released version
+To deploy a released version of the solution go to the [Releases](https://github.com/microsoft/Broadcast-Development-Kit/releases) page and download the Zip file for the version of the Management API you want to deploy.
+
+Then, using **Azure CLI** (either locally or in the Azure Portal), run the following command to deploy the Zip file:
+
+```
+az webapp deployment source config-zip --resource-group <resource_group> --name <app-name> --src <zip_file_path>
+```
+
+## Building and deploying from the source code
 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**.

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

@@ -1,7 +1,7 @@
 # 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.
+To host the Bot Orchestrator function a Function App must be created in Azure. This document shows how to create the Function App for the Bot Orchestrator.
 
 ## Dependencies
 To create the Function App service needed to deploy the Orchestrator function, the following resources must be already created:
@@ -14,7 +14,7 @@ To create the Function App service needed to deploy the Orchestrator function, t
 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.
+    - ***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).

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

@@ -1,7 +1,7 @@
 # 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.
+To run the Management API and Bot Orchestrator function in Azure an you must created an App Service Plan. This App Service Plan will define the resources available to execute the apps.
 
 ## Dependencies
 To continue with the App Service Plan, the following dependencies need to be created:
@@ -11,13 +11,13 @@ To continue with the App Service Plan, the following dependencies need to be cre
 ### 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.
+- ***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.
+    - ***Sku and size:*** Basic B1.
-    > **NOTE**: This tier (Shared D1) is to reduce costs during the test. It can be increased if needed.
+    > **NOTE**: The tier (Shared D1) can be used to reduce costs during the test. However note that this can cause issues, like the Azure Functions not processing the messages from the queues.
 
 ### 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.
@@ -28,7 +28,7 @@ Fill the fields in the creation wizard with the following information:
 
     ![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**.
+1. Next, in the **Recommended pricing tiers** panel, select the **Dev/Test** tab, then select the **B1** tier, and click on **Apply**.
 
     ![Recommended pricing tiers](images/service_plan_select_tier.png)
 

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

@@ -2,7 +2,7 @@
 
 ## Getting Started
 
-This document shows how to create and configure the Storage account for the solution core components. This Storage account will be used to store the environment settings in `json` format, the wildcard SSL certificate in `pfx` format, and the queues that are consumed by the Azure Functions. 
+This document shows how to create and configure the Storage account for the solution core components. This Storage account will be used to store the environment settings in `json` format and the queues that are consumed by the Azure Functions. If you want to delegate the installation of the wildcard SSL certificate to the Bot Service, you will also store the certificate in `pfx` format in this storage account.
 
 To create a Storage account in Azure, please review the following Microsoft [documentation](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-portal).
 
@@ -13,15 +13,15 @@ The following list shows the resources required to complete the configuration of
 
 - [Azure Bot app registration](../prerequisites/azure_bot.md).
 - [Cosmos DB](cosmos_db.md).
-- [SSL Certificate](../prerequisites/readme.md).
+- [SSL Certificate](../prerequisites/README.md).
-- [Azure Virtual Machine (where the bot service is hosted)](bot_service_virtual_machine.md).
+- [Azure Virtual Machine (where the bot service is hosted)](virtual_machine.md).
 - [Management API](web_app_and_app_service_plan.md).
 - [Bot Service API app registration](app_registrations.md#how-to-setup-bot-service-api-app-registration).
 - [Application Insights](application_insights.md).
 
-### Settings.
+### Settings
 Create this storage account with the following settings:
-- ***Resource Group:*** Select the [resource group](readme.md#architecture-resource-group) created for the solution architecture.
+- ***Resource Group:*** Select the [resource group](README.md#architecture-resource-group) created for the solution architecture.
 - ***Storage account Name***: A meaningful name.
 - ***Region***: Same region as the rest of the resources.
 - ***Performance***: Standard.
@@ -38,7 +38,7 @@ Once this Storage account is created, create a new container with the following
 
 To create a new Container, please review the following Microsoft [documentation](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal#create-a-container)
 
-Once the config container is created, upload the Bot Service settings and the wildcard SSL certificate files to it.
+Once the config container is created, upload the Bot Service settings in it. If you plan to delegate the installation of the certificate to the Bot Service, will need to upload the wildcard SSL certificate files to it too.
 
 ### Environment ***.json*** file settings example:
 Below there is a json file template with placeholders values you need to complete and upload to storage account before using the bot for the first time.
@@ -117,12 +117,12 @@ Below there is a json file template with placeholders values you need to complet
 | cosmosDbEndpointUrl                    | Endpoint URL of the [Cosmos DB](cosmos_db.md) created.                              |
 | cosmosDbPrimareyKey                    | Primary key of the [Cosmos DB](cosmos_db.md) created.                               |
 | cosmosDbDatabaseName                   | Database name of the [Cosmos DB](cosmos_db.md) created.                             |
-| pfxCertificatePassword                 | Password of the wildcard certificate uploaded to the Storage account.               |
+| pfxCertificatePassword                 | **Only needed if you want to delegate the installation of your certificate to the Bot Service**. Password of the wildcard certificate uploaded to the Storage account.               |
 | pfxCertificateThumbprint               | Thumbprint of the wildcard certificate uploaded to the Storage account.             |
 | managementApiURl                       | URL of the [Management API](web_app_and_app_function.md) (without https:// prefix). |
 | tenantIdAzureBotServiceApiClientId     | Tenant Id of the app registration for the [Bot Service API](app_registrations.md#how-to-setup-bot-service-api-app-registration).          |
-| botServiceApiClientId                     | Client Id of the app registration for the [Bot Service API](app_registrations.md#how-to-setup-bot-service-api-app-registration). |
+| botServiceApiClientId                  | Client Id of the app registration for the [Bot Service API](app_registrations.md#how-to-setup-bot-service-api-app-registration). |
-| appInsigtsKey                          | Application Insights key of the [Application Insights](application_insights.md) resource. |
+| appInsightsKey                         | Application Insights key of the [Application Insights](application_insights.md) resource. |
 
 ## Upload file to container
 Here's explains how to upload the `json file` into the container that was created.

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

@@ -1,14 +1,13 @@
-# Bot Service Virtual Machine
+# 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).
+- [SSL Certificate](../prerequisites/README.md).
 
 ## Create the virtual machine in Azure
 
@@ -53,43 +52,31 @@ Once the virtual machine is created, we must add inbound rules in the network se
 | RTMP            | 1935-1936, 1940-1949 | TCP      | Used to inject & extract RTMP content.                       |
 | RTMPS           | 2935-2936, 2940-2949 | TCP      | Used to inject & extract RTMPS content.                      |
 
-### Configure the virtual machine
+## 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
+### SSL Certificate
+Your wildcard SSL certificate can be installed in the virtual machine using one of these approaches:
+
+1. **Install the SSL certificate manually in the VM.** The main advantage of this is that you won't need to upload your PFX and password to the storage account, but you will need to change the certificate manually once it expires. To use this approach check the instructions in [Manual installation of your domain certificate](../common/install_domain_certificate.md).
+
+2. **Automatically through the Bot Service.** The main advantage is that the Bot Service will take care of installing the latest certificate as long as it is available in the storage account. The downside is that you will need to upload the certificate and password to the storage account. To delegate the installation to the Bot Service, check the instructions in [Storage Account](storage_account.md).
+
+### 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
+### VCRedist
 Download [VCRedist](https://aka.ms/vs/16/release/vc_redist.x64.exe) and install it.
 
-#### NGINX
+### NGINX
 Follow this guide [How to Install and configure NGINX with RTMP module on Windows](../common/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.
 
@@ -105,47 +92,11 @@ In order to run the bot, we need to configure some environment variables that th
 | 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.  |
+| 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
+## Bot Service
-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.
+For instructions on how to deploy the Bot Service to the virtual machine you created check the [Deploy the Bot Service](deploy_bot_service.md) document.
-
-> **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/web_app_and_app_service_plan.md

@@ -1,7 +1,7 @@
 # Web App
 
 ## Introduction
-In order to host the Management API, a Web App service must be created. This document is intend to show, how to create a Web App in the resource group created for the architecture solution.
+To host the Management API a Web App service must be created in Azure. This documents shows how to create the Web App for this API.
 
 ## Dependencies
 To create the Web App needed to deploy the Management API, the following resources must be already created:
@@ -13,7 +13,7 @@ To create the Web App needed to deploy the Management API, the following resourc
 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.
+    - ***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).

docs/how-to-run-the-solution-locally/README.md

@@ -3,9 +3,12 @@
 ## About
 This document details the required software to be installed and the necessary steps you must follow to configure and run the solution locally.
 
+> **IMPORTANT**: These instructions will configure the solution to run in **Local mode**. This mode is designed to **disable most authentication checks** to make it easier for a developer to run the solution in their local environment. However, these settings should never be used when deploying this solution to Azure. For instructions on how to properly configure this solution in Azure, go to [How to Run the Solution in Azure](../how-to-run-the-solution-in-azure/README.md).
+
 ## Getting Started
 
 - [Requirements](#requirements)
+  - [General prerequisites](#general-prerequisites)
   - [Microsoft Azure Storage Emulator](#microsoft-azure-storage-emulator)
   - [Visual Studio 2019](#visual-studio-2019)
   - [Cosmos DB Emulator](#cosmos-db-emulator)
@@ -21,6 +24,13 @@ This document details the required software to be installed and the necessary st
 - [Testing the application](#testing-the-application)
 
 ## Requirements
+
+### General prerequisites
+
+Before running the solution locally, please make sure you have the all the prerequisites listed in [Prerequisites](..\prerequisites\README.md).
+
+Also, if you haven't already, make sure you have setup your [Azure Bot](..\prerequisites\azure_bot.md) too, as this still needed if you plan to run the solution locally.
+
 ### Microsoft Azure Storage Emulator
 Download and Install [Azure Storage Emulator](https://docs.microsoft.com/en-us/azure/storage/common/storage-use-emulator#get-the-storage-emulator)
 
@@ -155,41 +165,8 @@ Once this command is executed a message like the following will be displayed, th
 > ***OPTIONAL:*** Add `C:\ngrok` path where the .exe file is located to the Path environment variable. If you add it, you will not have to change the directory in the terminal every time you want to run ngrok.
 
 ### Domain Certificate
-Having the [pfx certificate mentioned in the prerequisites](../prerequisites/readme.md) double click on it to run the certificate import wizard.
 
-On the first screen, select `Local machine` as the Store Location and click `Next` (Windows may ask for administrator rights).
+You will need to install the [pfx certificate mentioned in the prerequisites](../prerequisites/README.md) in your local environment. You can find instructions on how to do this in document [Manual installation of your domain certificate](../common/install_domain_certificate.md).
-
-|![Import Certificate](images/import_certificate.png)|
-|:--:|
-|*Certificate Import Wizard*|
-
-Click `Next` on the File to import step.
-
-In the Privacy Key Protection step, the wizard will ask for the password to read the certificate's private key, complete it and leave the rest of the settings as-is and click next.
-
-|![Import Certificate](images/certificate_password.png)|
-|:--:|
-|*Complete the password to read the certificate*|
-
-Finally, in the Certificate Store selection, click on `Browse` and select `Personal`. Then continue with the rest of the wizard.
-
-Later it will be necessary to obtain the certificate thumbprint to complete the botservice configuration. To obtain it press Win+R keys, complete the input with `certlm.msc` and press `Ok`.
-
-|![Run Certificate](images/run_certificate.png)|
-|:--:|
-|*Complete the input and press Ok*|
-
-Navigate to `Certificates - Local Computer\Personal\Certificates`, search for the name of the certificate and open it (Either by double clicking or left click and open).
-
-|![Run Certificate](images/certificate_personal.png)|
-|:--:|
-|*Search the certificate and open it*|
-
-Go to details tab and search for Thumbprint field, select it, and copy its value, you will use it later.
-
-|![Run Certificate](images/certificate_thumbprint.png)|
-|:--:|
-|*Copy the thumbprint of the certificate*|
 
 ## Configure the Backend Solution to run locally
 
@@ -301,8 +278,6 @@ clientSecretAzureBotAppRegistration | Client secret of Azure bot [app registrati
 cosmosDbPrimaryKey | [Azure Cosmos DB Emulator primary key, can be found in the data explorer of the emulator](#cosmos-db-emulator).
 cosmosDbDatabaseName | Name of the database that the solution will create in Cosmos DB Emulator.  E.g.: `BroadcastDevelopmentKitDb`
 
-
-
 ### Configure BotService
 
 In the solution explorer, go to the `BotService` project (under `src/applications`), open the `Properties` folder and replace the `launchSettings.json` with the following configuration.
@@ -394,7 +369,7 @@ clientIdAzureBotAppRegistration | Client Id of the [app registration](../prerequ
 clientSecretAzureBotAppRegistration | Client secret of the [app registration](../prerequisites/azure_bot.md).
 cosmosDbPrimaryKey | [Azure Cosmos DB Emulator primary key, can be found in the data explorer of the emulator](#cosmos-db-emulator).
 cosmosDbDatabaseName | Name of the database that the solution will create in Cosmos DB Emulator.  E.g.: `BroadcastDevelopmentKitDb`
-certificateThumbprint | Thumbprint of the installed certificate.
+certificateThumbprint | Thumbprint of the installed certificate. If you don't know your certificate thumbprint, follow the instructions [here](../common/install_domain_certificate.md#obtaining-the-certificate-thumbprint) to obtain it.
 appInsightInstrumentationKey | ***`Optional:`*** by default leave it empty or if you have an instance of Application Insights you can store the log messages by entering an instrumentation key.
 
  To finish Configure the configuration file you have to use ngrok. The following image serves as a guide to know in a simple way where to take the values.