/arm-templates-for-samples

For soliciting feedback on ARM templates

Bot Framework ARM Templates:

This README contains information on how to deploy your local bot to Azure.

Table of Contents:

Prerequisites:

Install Azure CLI >=2.0.61:

Visit the following page to find the correct installer for your OS:

Deploying via ARM template (with new Resource Group)

We recommend provisioning Azure resources through ARM templates via the Azure CLI. It is also possible to deploy ARM templates via the Azure Portal, PowerShell and the REST API.

To install the latest version of the Azure CLI visit this page.

1. Create an App registration

Your bot requires a Registered app that provides the bot access to the bot framework service for sending and receiving authenticated messages.

To create an App registration via the Azure CLI, perform the following command:

# Replace "displayName" and "AtLeastSixteenCharacters_0" with your specified values.
# The --password argument must be at least 16 characters in length, and have at least 1 lowercase char, 1 uppercase char, 1 numerical char, and 1 special char (e.g. !?-_+=)
az ad app create --display-name "displayName" --password "AtLeastSixteenCharacters_0" --available-to-other-tenants

This command will output JSON with the key "appId", save the value of this key for the ARM deployment, where it will be used for the "appId" parameter. The password provided will be used for the "appSecret" parameter.

It is also possible to create and manage Registered Apps via the Azure portal. Be sure to also create a password when creating the application.

2. Create a resource group and the Azure resources

Next, you'll use the ARM template to create the resources specified in it. In this case, we are provding App Service Plan, Web App, and Bot Channels Registration.

Note: The botId parameter should be globally unique and is used as the immutable bot ID. Also used to configure the displayName of the bot, which is mutable.

# Pass in the path to the ARM template for the --template-file argument.
# The argument for --template-file comes from the name of the templates located in the same folder as this README.
az deployment create --name "<name-of-deployment>" --template-file "template-with-new-rg.json" --subscription "<subscription-guid>" --location "westus" --parameters appId="<msa-app-guid>" appSecret="<msa-app-password>" botId="<id-or-name-of-bot>" botSku=F0 newAppServicePlanName="<name-of-app-service-plan>" newWebAppName="<name-of-web-app>" groupName="<new-group-name>" groupLocation="westus" newAppServicePlanLocation="westus"

These instructions shows how to zipdeploy your code using az webapp. App Service's default behavior for zipdeploy is to not build the code or install any dependencies (e.g. you must zip up your binaries or your node_modules folder).

For more information on Kudu, visit their GitHub repository.

To see all available ARM template parameters and their descriptions, scroll down or click here.

3. Retrieve or create necessary IIS/Kudu files via az bot

For C# bots this command is necessary if Kudu is configured to build on zip deployment (i.e. SCM_DO_BUILD_DURING_DEPLOYMENT=true):

# For C# bots, it's necessary to provide the path to the .csproj file relative to --code-dir. This can be performed via the --proj-file-path argument
az bot prepare-deploy --lang Csharp --code-dir "." --proj-file-path "MyBot.csproj"
# The command would resolve --code-dir and --proj-file-path to "./MyBot.csproj"

For Node.js bots:

# This command will fetch a web.config which is needed for Node.js apps to work with IIS on Azure App Services
az bot prepare-deploy --code-dir "." --lang Node

4. Zip up the code directory manually

When using the non-configured zipdeploy API to deploy your bot's code, Web App/Kudu's behavior is as follows:

Kudu assumes by default that deployments from zip files are ready to run and do not require additional build steps during deployment, such as npm install or dotnet restore/dotnet publish.

As such, it is important to include your built code and with all necessary dependencies in the zip file being deployed to the Web App, otherwise your bot will not work as intended.

5. Deploy code to Azure using az webapp

At this point we are ready to deploy the code to the Azure Web App.

az webapp deployment source config-zip --subscription "<subscription-guid>" --resource-group "<new-group-name>" --name "<name-of-web-app>" --src "Path/to/zipped/code.zip" 
# The --timeout argument is an optional and configurable timeout in seconds for checking the status of deployment.

Deploying via ARM template (with preexisting Resource Group)

We recommend provisioning Azure resources through ARM templates via the Azure CLI. It is also possible to deploy ARM templates via the Azure Portal, PowerShell and the REST API.

To install the latest version of the Azure CLI visit this page.

1. Create an App registration

To create an App registration via the Azure CLI, perform the following command:

# Replace "displayName" and "AtLeastSixteenCharacters_0" with your specified values.
# The --password argument must be at least 16 characters in length, and have at least 1 lowercase char, 1 uppercase char, 1 numerical char, and 1 special char (e.g. !?-_+=)
az ad app create --display-name "displayName" --password "AtLeastSixteenCharacters_0" --available-to-other-tenants

This command will output JSON with the key "appId", save the value of this key for the ARM deployment, where it will be used for the "appId" parameter. The password provided will be used for the "appSecret" parameter.

It is also possible to create App registrations via apps.dev.microsoft.com or via the Azure portal. Be sure to also create a password when creating the application.

2. Create a resource group and the Azure resources

Note: The botId parameter should be globally unique and is used as the immutable bot ID. Also used to configure the displayName of the bot, which is mutable.

Command with new App Service Plan:
# Pass in the path to the ARM template for the --template-file argument.
# The argument for --template-file comes from the name of the templates located in the same folder as this README.
az group deployment create --name "<name-of-deployment>" --resource-group "<name-of-resource-group>" --template-file "template-with-preexisting-rg.json" --subscription "<subscription-guid>" --parameters appId="<msa-app-guid>" appSecret="<msa-app-password>" botId="<id-or-name-of-bot>" newWebAppName="<name-of-web-app>" newAppServicePlanName="<name-of-app-service-plan>" appServicePlanLocation="westus"
Command with preexisting App Service Plan:
# The difference between this example command and the previous command is
# this command uses "existingAppServicePlan" as a parameter instead of "newAppServicePlanName"

# If both parameters are passed in, the ARM template provided will try to create a new Web App on the "existingAppServicePlan".
# Pass in the path to the ARM template for the --template-file argument.
# The argument for --template-file comes from the name of the templates located in the same folder as this README.

az group deployment create --name "<name-of-deployment>" --resource-group "<name-of-resource-group>" --template-file "template-with-preexisting-rg.json" --subscription "<subscription-guid>" --parameters appId="<msa-app-guid>" appSecret="<msa-app-password>" botId="<id-or-name-of-bot>" newWebAppName="<name-of-web-app>" existingAppServicePlan="<name-of-app-service-plan>" appServicePlanLocation="westus"

These instructions shows how to zipdeploy your code using az webapp. App Service's default behavior for zipdeploy is to not build the code or install any dependencies (e.g. you must zip up your binaries or your node_modules folder).

For more information on Kudu, visit their GitHub repository.

To see all available ARM template parameters and their descriptions, scroll down or click here.

3. Retrieve or create necessary IIS/Kudu files via az bot

For C# bots this command is necessary if Kudu is configured to build on zip deployment (i.e. SCM_DO_BUILD_DURING_DEPLOYMENT=true):

# For C# bots, it's necessary to provide the path to the .csproj file relative to --code-dir. This can be performed via the --proj-file-path argument
az bot prepare-deploy --lang Csharp --code-dir "." --proj-file-path "MyBot.csproj"
# The command would resolve --code-dir and --proj-file-path to "./MyBot.csproj"

For Node.js bots:

# This command will fetch a web.config which is needed for Node.js apps to work with IIS on Azure App Services
az bot prepare-deploy --code-dir "." --lang Node

4. Zip up the code directory manually

When using the non-configured zipdeploy API to deploy your bot's code, Web App/Kudu's behavior is as follows:

Kudu assumes by default that deployments from zip files are ready to run and do not require additional build steps during deployment, such as npm install or dotnet restore/dotnet publish.

As such, it is important to include your built code and with all necessary dependencies in the zip file being deployed to the Web App, otherwise your bot will not work as intended.

5. Deploy code to Azure using az webapp

At this point we are ready to deploy the code to the Azure Web App.

az webapp deployment source config-zip --subscription "<subscription-guid>" --resource-group "<new-group-name>" --name "<name-of-web-app>" --src "Path/to/zipped/code.zip" 
# The --timeout argument is an optional and configurable timeout in seconds for checking the status of deployment.