Update docs to deploy released versions and provide alternatives to install the certificate

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,8 +16,9 @@ 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).
-        - [Function App and App service plan](function_app_and_app_service_plan.md).
+        - [App Service Plan](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).
         - [Event Grid](configure_event_grid.md).
@@ -29,6 +30,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.  
 

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

@@ -53,32 +53,45 @@ 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.
+## Bot 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.
 
-Go to the Solution Explorer, right-click on BotService project and click **Publish**.
+### 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, and edit the following settings:
+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
@@ -88,7 +101,7 @@ In the publish tab, configure the Target Location, and edit the following settin
 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.
+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.
 
 ### 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.
@@ -110,12 +123,12 @@ In order to run the bot, we need to configure some environment variables that th
 
 > **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
+## 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
+### 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, 
@@ -130,9 +143,9 @@ $env:CERTIFICATE_FILE_NAME = '{{certFileName}}'
 .\BotService.exe --console
 ```
 
-> **NOTE**: Enable remote signed script for Powershell `set-executionpolicy remotesigned`.
+> **NOTE**: You might need to enable remote signed scripts in Powershell using the command `set-executionpolicy remotesigned`.
 
-#### As a Windows Service
+### 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)

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:

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:
@@ -16,8 +16,8 @@ Fill the fields in the creation wizard with the following information:
 - ***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.
+    - ***Sku and size:*** Basic B1.
+    > **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).
 
@@ -19,7 +19,7 @@ The following list shows the resources required to complete the configuration of
 - [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.
 - ***Storage account Name***: A meaningful name.
@@ -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). |
-| 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/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:

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).
-
-|![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*|
+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).
 
 ## 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.