Guide: Installing the test bed for development use

Track	Test bed operation

This guide walks you the installation a new test bed instance for development purposes.

What you will achieve

At the end of this guide you will have a fully functioning test bed installation. This test bed instance may be used as:

A demo instance for you to evaluate whether the test bed is a good fit for your needs.

A local development instance, on your workstation or a shared environment, on which you can experiment and prepare the test suites and test services needed by your project.

This guide acts as a counterpart to the test bed’s production installation guide.

What you will need

About 30 minutes.

A text editor.

A web browser.

A machine with at least a dual core CPU, 4 GBs of RAM and 30 GBs of free storage. This machine should also be able to access the internet (for software installations).

Administrator privileges on the target machine.

A basic understanding of networking (e.g. ports) and be comfortable using a command prompt.

How to complete this guide

Completing the installation’s steps involves the preparation of your installation script and the execution of commands on a command line interface.

Steps

Carry out the following steps to complete this guide.

Step 1: Install required tools

Note

Using Kubernetes: The test bed can also be installed on Kubernetes via Helm chart or manifest files as described in the production installation guide. Using Docker is however simpler and better suited for development, and will be the approach considered in this guide.

The first step is to ensure that Docker is installed on the machine that will host the test bed. If you already have Docker ensure it is at least at version 17.06.0, otherwise you can follow Docker’s online instructions to install or upgrade it.

Once your installation is complete, you will be able to test it using the docker --version command. This should provide output as follows:

> docker --version

Docker version 23.0.5, build bc4487a

To complete your Docker setup you will also install Docker Compose, a tool for defining and running multi-container Docker applications (such as the test bed). You can check whether your Docker installation already includes Docker Compose by issuing the docker compose version command that should give output as follows:

> docker compose --version
Docker Compose version 2.17.3

The minimum version of Docker Compose you need is 2.0.0. If you don’t have Docker Compose already installed follow its installation guide to set it up.

Note

Use of Docker Compose: It is not strictly necessary to use Docker Compose for a test bed installation although it is highly advised given the simplifications it offers.

Step 2: Define the test bed’s configuration

First off create a folder on the machine you will install the test bed on. For the purpose of this guide lets assume this is:

/workspace/testbed

Within the testbed folder create file docker-compose.yml with the following contents:

volumes:
   gitb-repo:
   gitb-dbdata:

services:
   gitb-redis:
      image: isaitb/gitb-redis
      container_name: itb-redis
      restart: unless-stopped
   gitb-mysql:
      image: isaitb/gitb-mysql
      container_name: itb-mysql
      restart: unless-stopped
      volumes:
       - gitb-dbdata:/var/lib/mysql
      healthcheck:
       test: "/usr/bin/mysql --user=root --password=$$MYSQL_ROOT_PASSWORD --execute \"SHOW DATABASES;\""
       interval: 3s
       retries: 50
   gitb-srv:
      image: isaitb/gitb-srv
      container_name: itb-srv
      restart: unless-stopped
      environment:
       - CALLBACK_ROOT_URL=http://localhost:8080/itbsrv
      ports:
       - "8080:8080"
   gitb-ui:
      image: isaitb/gitb-ui
      container_name: itb-ui
      restart: unless-stopped
      ports:
       - "9000:9000"
      environment:
       - THEME=ec
      volumes:
       - gitb-repo:/gitb-repository
      depends_on:
       gitb-redis:
         condition: service_started
       gitb-mysql:
         condition: service_healthy
       gitb-srv:
         condition: service_started 

This is a YAML file that defines the components you will install as well as their configuration. To avoid issues with whitespace (YAML can be picky about that) you can download a correct copy from here. The contents of this file represent an example configuration from a development environment running on your localhost. It specifies how the test bed’s components are to be setup, specifically:

Two volumes named gitb-repo and gitb-dbdata are defined to persist the test bed’s data. These are defined as such so that other components can be removed or replaced without data loss.

itb-redis is a cache server used for user session management.

itb-mysql is the test bed’s database.

itb-srv is the test bed’s backend test engine that executes tests.

itb-ui is the test bed’s frontend that users access.

The following table summarises the configuration options specific to the test bed that you should be aware of and potentially adapt for your installation:

Component	Section/Property	Description
`itb-srv`	`environment/CALLBACK_ROOT_URL`	The base address for test engine call-backs.
`itb-srv`	`ports`	This is the port mapping for the test bed’s test engine on the local machine.
`itb-ui`	`environment/THEME`	Defines the UI theme to use. Use `ec` for a Commission theme or remove the property for a default GITB theme.
`itb-ui`	`ports`	This is the port mapping for the test bed’s user interface and APIs on the local machine.

The full set of configuration properties supported by the test bed are listed here.

Apart from these options, the docker-compose.yml file uses Docker Compose properties such as restart: unless-stopped that ensures containers are always running unless explicitly stopped. In addition, you may have noticed that the itb-mysql container definition includes a healthcheck to allow the itb-ui container to only start after the database is ready to accept connections. For a detailed description of such options and a better understanding of the docker-compose.yml file you can check out the Docker Compose file reference.

Note

Installing a production test bed instance: The configuration provided in this section is minimal and meant to provide development flexibility. When installing a test bed instance for production use you need to consider numerous additional points (see Guide: Installing the test bed for production use).

Installing on a remote server

The configuration we saw in the previous section assumes that you are setting up a developer instance on your local workstation. This approach allows for minimum setup hassle and highest efficiency while developing.

In case you are setting up a development instance on a remote server, you need to make some minor adjustments to your configuration to ensure a fully working installation. These relate to how you access the test bed on the remote server, taking into account its address (or domain name), ports and reverse proxy mappings (if a proxy is setup). These points are discussed in more detail in the production installation guide but in brief you would need to configure the following:

Property CALLBACK_ROOT_URL on itb-srv, to allow the test bed to receive remote callbacks.

Property TESTBED_HOME_LINK on itb-ui, to specify the home link for the test bed’s frontend.

Property AUTHENTICATION_COOKIE_PATH on itb-ui, in case you use a reverse proxy and map the test bed’s frontend to a specific path.

As an example, consider that you are deploying the test bed on a remote server with IP address 10.0.0.1, without going through a proxy, and using the default port mappings. In this case you need to adapt docker-compose.yml as follows:

services:
   ...
   gitb-srv:
      ...
      environment:
       ...
       - CALLBACK_ROOT_URL=http://10.0.0.1:8080/itbsrv
   gitb-ui:
      ...
      environment:
       ...
       - TESTBED_HOME_LINK=http://10.0.0.1:9000
   ...

In case you are using a proxy on the remote host and exposing the test bed over HTTP on port 80, using paths /itb and /itbsrv for the itb-ui and itb-srv components respectively, your configuration would be as follows:

services:
   ...
   gitb-srv:
      ...
      environment:
       ...
       - CALLBACK_ROOT_URL=http://10.0.0.1/itbsrv
   gitb-ui:
      ...
      environment:
      ...
       - TESTBED_HOME_LINK=http://10.0.0.1/itb
       - AUTHENTICATION_COOKIE_PATH=/itb
   ...

In addition, to this configuration you would also need to ensure your reverse proxy is configured appropriately to expose the test bed’s components.

Step 3: Install the test bed

Open a command prompt to the testbed folder (i.e. where you have your docker-compose.yml file). In this issue the docker compose up -d command from which you should see the following output:

docker compose up -d
...
Creating itb-srv ...
Creating itb-redis ...
Creating itb-mysql ...
Creating itb-srv
Creating itb-redis
Creating itb-srv ... done
Creating itb-ui ...
Creating itb-ui ... done

What this does is to first download all required test bed images (as well as the images they build upon) and then start up all services. The names you see (e.g. itb-srv) can be used to refer to individual containers (e.g. to inspect logs).

To ensure the test bed has completed its initialisation check the logs of itb-srv and itb-ui. For itb-srv issue docker logs -f itb-srv for which you should see output completing as follows:

> docker logs -f gitb-srv

...
31/01/2025 15:36:51 INFO  c.g.t.c.TestbedServiceContextListener - [] Started ITB test engine (itb-srv) - release 1.25.0
 _____ _______ ____                       _
|_   _|__   __|  _ \                     | |
  | |    | |  | |_) |  _ __ ___  __ _  __| |_   _
  | |    | |  |  _ <  | '__/ _ \/ _` |/ _` | | | |
 _| |_   | |  | |_) | | | |  __/ (_| | (_| | |_| |
|_____|  |_|  |____/  |_|  \___|\__,_|\__,_|\__, |
                                             __/ |
                                            |___/

You can exit the log display by issuing a CTRL-C. To check itb-ui issue docker logs -f itb-ui for which the output should complete as follows:

> docker logs -f itb-ui

...
31/01/2025 15:36:52 INFO  hooks.PostStartHook - Started ITB frontend (itb-ui) in production mode - release 1.25.0 (2025-01-31 09:35:19)
 _____ _______ ____                       _
|_   _|__   __|  _ \                     | |
  | |    | |  | |_) |  _ __ ___  __ _  __| |_   _
  | |    | |  |  _ <  | '__/ _ \/ _` |/ _` | | | |
 _| |_   | |  | |_) | | | |  __/ (_| | (_| | |_| |
|_____|  |_|  |____/  |_|  \___|\__,_|\__,_|\__, |
                                             __/ |
                                            |___/

Once again exit the log display by issuing a CTRL-C. You should now have a fully functioning test bed installation.

Alternative installation with Docker commands

If you have experience with Docker and prefer working with Docker commands directly you can also use them to install the test bed. The commands to execute (in sequence) would be as follows:

docker network create itb-net

docker create -v /var/lib/mysql --name itb-dbdata ubuntu

docker create -v /gitb-repository --name itb-repo ubuntu

docker run --name itb-mysql --net=itb-net -d --restart=unless-stopped \
--volumes-from itb-dbdata \
isaitb/gitb-mysql

docker run --name itb-redis --net=itb-net -d --restart=unless-stopped isaitb/gitb-redis

docker run --name itb-srv --net=itb-net -p 8080:8080 \
-e CALLBACK_ROOT_URL=http://localhost:8080/itbsrv \
-d --restart=unless-stopped \
isaitb/gitb-srv

docker run --name itb-ui --net=itb-net -p 9000:9000 --volumes-from itb-repo \
-d --restart=unless-stopped -e THEME=ec \
isaitb/gitb-ui

Note that the advised way to install the test bed is nonetheless to use Docker Compose, as it offers a better way to manage your configuration and automates most manual tasks.

Step 4: Test your installation

To test your installation log into the test bed using the default administrator account.

Open a browser window and navigate to http://localhost:9000 (assuming Docker is running natively on your localhost). You should be greeted with test bed’s welcome page:

You can now also try to log into the test bed using the default administrator account. To do this click on the Click to log in button at which point you should see the test bed’s login page:

The default administrator’s account is admin@itb which is set with an automatically generated password at startup. The value for this password is printed in the itb-ui container’s logs that can be inspected using command docker logs -f itb-ui:

...
###############################################################################

The one-time password for the default administrator account [admin@itb] is:

b1afbc39-8ad7-49f4-a9d9-0bcec942aef4

###############################################################################
...

Providing the listed password in the login form will prompt you to replace it, following which you should be greeted with the test bed’s empty home page:

From this point on you are free to setup and use the test bed as you please.

Note

Development mode: You will likely notice a Development mode notice in the interface’s footer. This highlights that this is a simplified instance that should not be used in production. For a production installation check Guide: Installing the test bed for production use.

Step 5: Manage the test bed

An optional additional step would be to experiment with managing your new test bed instance.

Managing the test bed is done as with any set of Docker containers. In fact, as we are using Docker Compose, management is actually simpler as you don’t need to treat individual components. The following list provides a set of commands that you would eventually be using. Note that when using the docker compose command you need to do so from the folder that contains the docker-compose.yml file):

Action	Command
Create and run the test bed	`docker compose up -d`
View a component’s log file (e.g. `itb-ui`)	`docker logs -f itb-ui`
Stop the test bed	`docker compose stop`
Start the test bed	`docker compose start`
Delete the test bed (keeping all data)	`docker compose down`
Delete the test bed (removing all data)	`docker compose down -v`
Obtain the latest test bed version	`docker compose pull`

If you have a running test bed and want to update it to the latest release you would use a combination of the above commands as follows:

docker compose pull to get any latest versions but not make any changes.

docker compose down to remove the previous containers but keeping your data.

docker compose up -d to create new containers based on the latest downloaded versions (reusing your previous data).

A detailed description on updating a test bed instance to the latest release is provided in Guide: Updating the test bed.

Summary

Congratulations! You have now completed your test bed installation for development use. In doing so you also installed Docker, Docker Compose and created a docker-compose.yml file to configure and automate your test bed’s installation and management.

Guide: Installing the test bed for development use

What you will achieve

What you will need

How to complete this guide

Steps

Step 1: Install required tools

Step 2: Define the test bed’s configuration

Installing on a remote server

Step 3: Install the test bed

Alternative installation with Docker commands

Step 4: Test your installation

Step 5: Manage the test bed

Summary

See also