Skip to content

Installation as Azure Multi-Container App

Botium Box is perfectly compatible with the Azure cloud. This article shows several ways how to install it.


Prepare Azure Account

Create an Azure resource group for Botium Box. Adapt it to your Azure region, and name the resource group however you want. You can do this in the Azure portal, or by using the Cloud shell:

az group create --name BotiumResourceGroup --location "West Europe"

Adapt docker-compose-azure.yml

Adapt your docker-compose-azure.yml

  • fill in the Botium Box license key into the LICENSE_KEY environment variable


Take care to add the full license key as received from us, otherwise the Botium Box won't start and you will receive an error message about an invalid license.

Create Azure Backend Service

Botium Box depends on other backend services:

  • MySQL for persistant storage of data

  • Redis as distributed message queue (included in docker-compose)

Create Azure MySQL Database

See here for instructions.


Make sure to select the Azure Database for MySQL component - there are other MySQL components available as well.

It is important to enable the MySQL firewall to be accessible from your Botium Box installation (enable Allow access to Azure services).

You need the connection information to the MySQL database, see here how to get it.

Open the docker-compose-azure.yml and add the MySQL connection information in the DATABASE_URL variable:

      DATABASE_URL: mysql://root:password@mysql-server:3306/box@prod13
  • replace mysql-server with "Server name" from Azure MySQL
  • replace root with "Server admin login name" from Azure MySQL
  • replace password with the password you selected

Installation of Botium Box Multi-Container App

Botium Box can be installed in a single web-app on Azure. This is the most easy installation option.


This tutorial follows these instructions.

Create Azure App Service Plan

Create an Azure service plan in the resource group. Make sure to

  • select Linux as operating system

  • select at least an S2 SKU for production usage (S1 won’t do, see system requirements).

Create Azure Web App

Create an Azure Web App in the resource group and for the service plan you created above.

Select Docker-Image and Linux as operating system.

In the next step, you have to define your docker settings.

  • Select Docker Compose and Docker Hub

  • Upload the file docker-compose-azure.yml from the Botium Box distribution (adapted to your environment in the previous steps)

Finish the creation of the app and wait until completion.

Configure Azure Web App

Open the web app settings and add two application settings:


  • WEBSITES_PORT => 4000

In addition, we highly recommend to enable logging for docker containers.

Wait for Completion

It can take a while (up to half an hour) for the configuration to complete, so be patient. Azure now downloads, unpacks and runs all of the involved docker images, this can take a while.


In case something goes wrong, we recommend to use Kudu for troubleshooting.

Copy Botium Box Directories

You can use an FTP client to connect the Azure server and upload the content of the resources and testsets folder of the Botium Box distribution to their counterparts on the Azure server. Restart the app afterwards.

Open Botium Box in Web Browser

Botium Box now accessible at Azure Web App address, you can now point your browser to it.

Optional: Additional Botium Box Agents

The default configuration includes just one agent. To increase the agent count, duplicate the agent section in the docker-compose-azure.yml file, and upload it to the Azure portal again.


Make sure to adapt the BOTIUMBOX_AGENT_NAME environment variable to something unique for the duplicated agent section.

It will take several minutes for restarting, then you have additional agents for test case processing available.

Updating Botium Box

Updating Botium Box is way more easy then the initial setup on Azure.

Making a Database Backup

It is highly recommended to make a database backup before starting a software update.


Botium Box is built in a way to do automatic database migrations wherever possible, but we strongly advice to act according to Murphy’s law.

You should design your own database backup strategy for your Azure database(s), see here as entry point.

Manual Preparation Steps

For certain Botium Box releases, there are manual migration steps to be done. Please consult Botium Box Migration Steps if it applies to the update in question.

Rebuilding and Restarting Botium Box

In the Azure portal, open the app service hosting your Botium Box, go to Container Settings and update the docker compose configuration there (upload or copy/paste the docker-compose-azure.yml from the Botium Box distribution).

Restart the app service and wait a couple of minutes.

Verify Botium Box version

Open Botium Box in your webbrowser and verify the update by opening the Version menu in the Settings section.

Manual Finalization Steps

For certain Botium Box releases, there are manual migration steps to be done. Please consult Botium Box Migration Steps if it applies to the update in question.

Logout and Login

To reset the client session, please logout and login again with your webbrowser.


Most important is to know how to retrieve the docker logfiles. Azure app services include Kudu for most easily retrieving the Docker logfiles. Start Kudu by opening Advanced Tools in the Developer Tools menu, and clicking on Go.

You can download and browse the docker logfiles here -


The logfiles from the Botium Box agents have the ending agent_docker.log while the logfiles from the Botium Box server have the ending web_docker.log - what logfile you need depends on what you want to look up.