Skip to content

Installation Instructions (On-Premise)

Installations instructions for Botium Box Enterprise Edition

Check Requirements

Check the hardware and software requirements before starting the installation. Especially, check your Docker installation before proceeding:

$ docker run hello-world

Getting the Software

Botium Box is delivered as a set of prebuilt Docker images. Download or clone this Github Repository first to get the Docker compose definitions.

Botium Box follows agile development methods, a new release is published every 2-3 weeks. So we strongly recommend to set up your environment in a way to allow for regular software updates.

$ git clone
$ cd botium-box-premium-dist

The repository contains several docker-compose files:

  • docker-compose.yml - the plain Botium Box distribution with only required components and web/worker containers separated
  • docker-compose-standalone.yml - the plain Botium Box distribution with only required components and web/worker combined in one container
  • docker-compose-with-kibana.yml - Botium Box including Kibana, the log analytics dashboard
  • docker-compose-azure.yml - for running Botium Box in the Azure cloud

By default, docker-compose uses the file docker-compose.yml. If you want to use one of the other files, you have to add the -f docker-compose-kibana.yml switch to all docker-compose statements below.

Linux only: Configure Folder and Volume Permissions

Botium Box requires several directories on the host system. Those directories are mapped as Docker volumes in the docker-compose.yml and default to the current directory - make sure that the docker container users have read/write access to these directories:

  • testsets - mkdir -p testsets && sudo chown -R 1000:1000 testsets
  • resources - mkdir -p resources && sudo chown -R 1000:1000 resources
  • botiumwork - mkdir -p botiumwork && sudo chown -R 1000:1000 botiumwork
  • mysql - mkdir -p mysql && sudo chown -R 999:999 mysql

The *mysql *is especially important, as this directory holds the data of the MySQL database backing the Prisma data store.

Optionally: Create custom SSL certificate

For using SSL in the most secure way, add your own server certificates to the ./certs folder in the distribution.

If you don't want to use SSL, you can add an additional port mapping 80:80 to the nginx service in the docker-compose.yml file and use http instead of https to connect to the Botium Box.

Optionally: Add additional agents

By default, the Botium Box *docker-compose.yml *includes exactly one Botium Box agent. If you have licensed more than one agent, you have to adapt it to launch all the licensed agents. There are several options available to launch additional agents.

Edit docker-compose-standalone.yml

When using the standalone Botium Box image, you can change the "BOTIUMBOX_AGENT_COUNT" environment variable in docker-compose-standalone.yml.

Edit docker-compose.yml

Add additional agent services in the docker-compose.yml file by copying the existing service definition. Make sure to change the docker service identifier.

Use "docker-compose --scale"

Another option is to use the --scale command line switch to docker-compose when starting the Botium Box (see below):

docker-compose up -d --scale agent=10

Use "docker-compose run"

You can use this command to start new agents one by one:

docker-compose run -d --name botiumbox_agent_1 agent

docker-compose run -d --name botiumbox_agent_2 agent


Optionally: Botium Coach Worker (for NLP Testing)

In case you plan to do NLP Testing, you have to enable the Botium Coach Worker component before launching Botium Box. In docker-compose.yml:

  • Either install the Botium Coach Worker on a separate machine or docker network, or uncomment the coach container section (recommended)
  • Uncomment the environment variable COACH_WORKER_ENDPOINT to point to the coach services (including the version suffix like
  • In case the worker is protected with an API Key, add an environment variable COACH_WORKER_APIKEY (not required in default installation)

Optionally: Botium Spech Processing (for Voice Testing)

In case you plan to do Voice Testing, you have to enable the Botium Speech Processing component before launching Botium Box. In docker-compose.yml:

  • Install Botium Speech Processing - see Github Repository
  • Uncomment the environment variable SPEECH_PROCESSING_ENDPOINT to point to the service
  • In case the service is protected with an API Key, add an environment variable SPEECH_PROCESSING_APIKEY

Add Botium Box License Key

There are two options how to hand over the license key to Botium Box - by environment variable or by license key file.

License Key File

This is the preferred way, as it doesn't involve changing the Botium Box deployment files.

Copy&Paste the license key into a text file named license.key and place this file in the resources folder of your Botium Box. Take care

  • that the file is UTF-8 encoded
  • that there is only and only and only the license key itself in the file, no additional spaces, no newlines
  • on Linux: that the uid 1000 has read access to this file

Environment Variable LICENSE_KEY

You have to add the license key you received from us to the docker-compose.yml file (see the environment variables section).

Optionally, you can use whatever other mechanism is available in your infrastructure to hand over environment variables to a Docker container.

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.

Optionally: Change Default Password

The default password for accessing the Botium Box is nooneknows. This password for the default users is set once on first starting the Botium Box. You can use another password as default password by handing over the environment variable SEED_PASSWORD with your desired password, you can do this by adding it in the docker-compose.yml file.

Start the Botium Box

Finally, the command to start everything:

docker-compose up -d

When you updated any of the docker images (including Botium Box images), then follow the Update Instructions

For showing the output:

docker-compose logs -f

Open the Botium Box in the web browser

Point your browser to https://your-botium-box-host or http://your-botium-box-host:4000

Note: you will receive an SSL warning when using HTTPS (Botium Box comes with self-signed certificates).

Usually, the IP Adress is (for localhost). When using docker toolbox (on older Windows workstations), you have to find out the IP address to use by running the command docker-machine ip <instance-name>

Botium Box Default Users

Botium Box comes with some pre-defined users representing the pre-defined roles:

  • admin
  • testmanager
  • tester
  • guest

The default password for all of these users (if not changed as described above) is nooneknows

Optionally: Open the Kibana Log Dashboard in the web browser

Point your browser to http://your-botium-box-host:5601

The default user is elastic, the default password is changeme

Installation Video

Installation FAQ