Deploying Bot Framework To Azure On Linux


Microsoft Bot Framework SDK for Node.js allows developers to build text and voice based chatbots and connect them to a variety of channels including Skype, MS Teams, Slack, Facebook, Telegram, SMS, email, and more.

As a Node.js bot developer you may have asked yourself - “Can I deploy my bot to Azure on Linux?” - and yes, it is now possible using the Azure App Service for Linux (Preview). This article will help you get started with Azure bot deployments on Linux using the Node.js SDK for Bot Framework. I will walk you though the steps to setup your bot with Continuous Deployment via GitHub, register your new bot in the Bot Framework Portal, configure required app settings, as well as test your bot connection via WebChat.

Setting up the development environment

In order to follow along with this tutorial you will need the following apps and accounts:

After installing and configuring all of the above listed software and accounts, continue to Step 1.

Step 1 - Sign in to GitHub and create a new project repository

Sign into GitHub and create a new repository for your Bot Framework project code. Upload your existing Node.js bot code, or copy any sample from the Microsoft/BotBuilder-Samples/Node project and upload the relevant files to your new GitHub repository. We will use this repository to configure Continuous Deployment for the Azure App Service. Once you have your bot code uploaded to GitHub, continue to the next step.

Step 2 - Create new app via the Azure Portal

Login to the Azure Portal with your MSA account and take a look at the left side menu. At the top click on the “+ New” button and a blade menu will slide out to the right. From there we can take a look at the App Service Options.

Create new service

Step 3 - Select Web App on Linux (Preview)

Deploying your Node Bot to the Linux app service will give you a few advantages such as Node.js version control, Docker integration and more options that we will cover later in this article.

Select Linux web app

Step 4 - Configure app name and resource group

In the next step, set your bot app short name, which will be used as part of your Azure URL. Additionally, I recommend setting a new Resource Group per bot that you create. This will keep all of your bot’s resources under a single tag, and you can be confident to controll only the objects related to this bot. For example, when creating multiple bots, it’s good to know I can delete or reconfigure one bot via the resource group, without affecting any other projects.

Configure app name and resource group

Step 5 - Configure Node.js version

Click on “Configure Container” at the bottom of the Web App create menu. Here you will see the available Node.js versions by clicking on the “Runtime Stack” dropdown menu. At the time of this writing, the Long Term Support (LTS) version of Node.js runtime is version 6.x.x so we will select the highest available version from the dropdown menu. Node will be updated regularly, so don’t be surprised if there are newer version not mentioned in this article. As always, Node and NPM versions need to synced up, so whenever there is a Node/npm update in the app service, don’t forget to update the “engines” attributes of your bot’s package.json file**.

Configure Node.js Version

Step 6 - Create app and pin to the Azure dashboard

Complete the process by checking the “Pin to dashboard” checkbox, and click “Create”.

Pin to Dashboard and Create App

Step 7 - Confirm new app created successfully

After any loading messages and notifications complete, you will see your app status overview page which provides options to stop and restart your app, as well as the public URL, FTP information and request/error monitoring widget.

App Created Successfully

Step 8 - Select deployment options

The next step is to configure Continuous Deployment via GitHub. Under the Deployment menu, click on “Deployment options”.

Deployment Options

From the “Deployment source” menu click on “Choose Source”. In the next menu, select “GitHub” as your source option.

Choose Source - GitHub

In the “Deployment source” menu, you will see options to select your account, repository, and branch you want to deploy. If this is your first time connecting to GitHub, you will be asked to confirm OAuth permissions for GitHub to interact with and share data with your Azure account. Finally, click “OK” to save your deployment source configuration.

Configure account and repository After you click “OK” your deployment will begin to download the lates files from GitHub and install them into your Web App container.

View Deployment Status

Now that Continuous Delivery is configured, pushing new code to your GitHub repository will trigger a rebuild and redeployment or your bot!

Check in code to redeploy

You can monitor bot deployments via the Deployment Options view in the Azure Portal.

Deployment status OK

Step 9 - Register your bot app on the Bot Framework Portal

Navigate to the Bot Framework Portal at https://dev.botframework.com/ and signin with your MSA account. Once you are signed in, click on “Register a bot” in the top menu.

Register your bot on the Bot Portal

On the next screen, in the “Bot profile” section, you can upload a custom icon to help users identify your bot. Underneath the icon, enter your bot’s name as it will appear in your channel, for example Skype. The bot name is the public name that your users will see. Next set the bot handle, this is the name you will use to reference your bot in your code. Finally, add a short description that gives your users a basic overview of your bot’s functionality or intended purpose.

Configure bot name, handle, and short description

Scroll down and set your bot’s messaging API endpoint. This will be the domain name you setup in Azure App Service plus the route /api/messages. In this example, our messaging endpoint is https://botframework-on-linux.azurewebsites.net/api/messages.

Configure the bot's API endpoint

After setting the messaging endpoint, click the button that says “Manage Microsoft App ID and password”. This will open a new browser tab on https://apps.dev.microsoft.com where you will see your App name and App ID. Just below the App ID, click the button “Generate New Password”.

Create Microsoft App ID and Password

A popup window will appear that contains your App password. Save the password and App ID to a secure location such as One Note for future reference. You will not see this information again, so it’s very important that you save this information as you will need to refer to it in later configuration steps.

Save App info - important!

Finally, click “Finish and go back to Bot Framework”. You will be redirected back to the Bot Framework Portal page to finish the bot configuration.

Finish and go back to Bot Framework Portal

You will see that the Bot Portal has populated your App ID in the Configuration section. Verify the “Admin” configuration section has your correct email address under “Owners”, click the “agree to terms” checkbox, and click “Register” to complete the new bot registration process.

Complete bot registration

A popup window will alert you that the bot was created successfully. Click “OK” and you will now see the bot properties page.

Bot Created OK

Step 10 - Add your App ID and password to the Azure App Service configuration settings

Now that you have registered your bot on the Bot Portal, we will use the App ID and password you saved earlier to configure our Azure App settings. Navigate back to https://portal.azure.com, open your app overview page and select “Application settings” from the left menu. Under “App settings”, add a new key-value pair for your MICROSOFT_APP_ID and one for the MICROSOFT_APP_PASSWORD. Paste in the keys you saved from the registration step, and click the “Save” button at the top.

Configure App ID and password in settings

Now that we have configured the App ID and password, we need to restart our bot app for the changes to take effect. Click on “Overview” in the left menu and click “Restart” at the top. After the app restarts it is time to verify our bot is connected via the Bot Portal.

Restart app

Step 11 - Test the connection to your bot app in the Bot Framework Portal

In the Bot Portal configuration page for your new bot you will see a section called “Test connection to your bot”. Click the “Test” button. If everything is working correctly you will see the text “Accepted” appear just under the “Test” button. In the WebChat window to the right, type a message to your bot. The bot will respond with “Greetings! I am a demo bot.”, followed by a choice menu which will display some example message types. Congratulations! Your new bot deployment is now online and working correctly.

Test connection in Bot Portal

Next Steps

Now that you have setup your bot’s project repository, and successfully configured Continuous Deployment via Azure App Service, checking in new code to GitHub will automatically trigger a redeployment of your bot. You can now proceed to channel configuration and further iterate on your bot’s core functionality.

Happy Making!

Nils Whitmont from the Bot Framework Team