Installation Instructions (On-Premise)
Installations instructions for Botium Box Enterprise Edition
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 https://github.com/codeforequity-at/botium-box-premium-dist.git $ 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.
When using the standalone Botium Box image, you can change the "BOTIUMBOX_AGENT_COUNT" environment variable in docker-compose-standalone.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: Enable Botium Coach Worker
In case you plan to use Botium Coach, you have to enable the components providing certain functionality before launching Botium Box. In docker-compose.yml or docker-compose-standalone.yml:
- Uncomment the environment variable COACH_WORKER_ENDPOINT to point to the coach services
- In case the worker is running protected with an API Key, add an environment variable COACH_WORKER_APIKEY
- Uncomment the coach container section to enable the container
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
Note: you will receive an SSL warning when using HTTPS (Botium Box comes with self-signed certificates).
Usually, the IP Adress is 127.0.0.1 (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:
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
- When running large test sets, Botium Box gets slower and slower
- What are the Docker volumes for in Botium Box ?
- Failed to parse license key: JsonWebTokenError: jwt malformed.
- I am receiving an error TLSV1_ALERT_PROTOCOL_VERSION when starting docker-compose
- I am receiving an error Are you trying to mount a directory onto a file (or vice-versa)? when starting docker-compose
- I am receiving errors from the mysql service (something with InnoDb) when starting docker-compose (on migration)
- I am getting docker error like: X509 Certificated signed by unknown authority
- Does Botium Box store the test data secure, reliable and long-term ?