Guide: Installing the test bed for development use
This guide walks you through the process of installing 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.
Carry out the following steps to complete this guide.
Step 1: Install Docker
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.
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:
testbed folder create file
docker-compose.yml with the following contents:
test: "/usr/bin/mysql --user=root --password=$$MYSQL_ROOT_PASSWORD --execute \"SHOW DATABASES;\""
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-dbdataare 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.
gitb-redisis a cache server used for user session management.
gitb-mysqlis the test bed’s database.
gitb-srvis the test bed’s backend test engine that executes tests.
gitb-uiis 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:
The IP address that external systems may use to contact the test bed for certain types of direct messaging.
The full address to access the test bed’s notification call-back interface. This must resolve to
These represent the port mappings for the test bed on the local machine.
Defines the UI theme to use. Use
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
gitb-mysql container definition includes a healthcheck to allow the
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
file you can check out the Docker Compose file reference.
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).
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 eventually see the following output:
docker compose up -d
Creating itb-srv ...
Creating itb-redis ...
Creating itb-mysql ...
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 you should check the logs of
docker logs -f itb-srv
for which you should see output completing as follows:
> docker logs -f itb-srv
12-Sep-2018 12:52:41.124 INFO [localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployWAR Deployment of web application archive /usr/local/tomcat/webapps/itbsrv.war has finished in 18,756 ms
12-Sep-2018 12:52:41.140 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["http-nio-8080"]
12-Sep-2018 12:52:41.151 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["ajp-nio-8009"]
12-Sep-2018 12:52:41.159 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in 18918 ms
You can exit the log display by issuing a
CTRL-C. To check
docker logs -f itb-ui for which the output should complete as follows:
> docker logs -f itb-ui
INFO 2018-09-12 12:52:32 [main] application - Application has started in development mode
INFO 2018-09-12 12:52:32 [main] play - Application started (Prod)
INFO 2018-09-12 12:52:33 [main] play - Listening for HTTP on /0.0.0.0:9000
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 \
docker run --name itb-redis --net=itb-net -d --restart=unless-stopped redis:7.0.11
docker run --name itb-srv --net=itb-net -p 8080-8090:8080-8090 \
-e gitb.messaging.server-ip-address=localhost \
-e gitb.messaging.callbackURL=http://localhost:8080/itbsrv/MessagingClient \
-d --restart=unless-stopped \
docker run --name itb-ui --net=itb-net -p 9000:9000 --volumes-from itb-repo \
-d --restart=unless-stopped -e THEME=ec \
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 you can log into the test bed’s user interface using the default administrator account.
Open a browser window and navigate to
http://localhost:9000 (assuming Docker is running natively on your localhost). If the installation was successful you
should see the 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:
Log in using the default administrator account of
email@example.com with password
test. Upon doing so you will be prompted to set a new password, 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.
Development mode: When accessing the test bed’s screens you will likely notice a Development mode notice in the 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
Create and run the test bed
View a component’s log file (e.g.
Stop the test bed
Start the test bed
Delete the test bed (keeping all data)
Delete the test bed (removing all data)
Obtain the latest test bed version
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 pullto get any latest versions but not make any changes.
docker compose downto remove the previous containers but keeping your data.
docker compose up -dto 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.
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.
With a running test bed you are now free to start using it to configure your testing strategy and execute tests. Concerning the test bed’s use make sure to check out the user guide (for test bed administrators). This contains detailed information on how to create your domain, specifications and test suites, as well as register the organisations and users that will be using them to test.
Given that this is a development instance, it is likely that you will eventually want to publish your setup to a production environment. If this is the case keep in mind that you can export your full setup from your development instance and then import it to production. Details on how to do this are provided in the administrator user guide.
In terms of using the test bed, the next logical step would be to create your first test suites. For help on this you have the following options:
Skip the step-by-step guides by downloading the test suite archives. You can use either the basic test suite created in Guide: Creating a test suite (download
here), or a more complete version created in Guide: Messaging in test cases (download
Refer to the GITB TDL documentation to get the complete details on how to create test suites.
To address advanced and domain-specific testing needs you may want to extend the test bed’s capabilities through separate GITB test services. Check out the GITB test services documentation on how to implement these and get started quickly using the available templates.
For more information on the Docker and Docker Compose tools, commands and properties used in this guide, check out the Docker online documentation.
Finally, in terms of further guides that would be of interest you should consider:
Guide: Installing the test bed for production use for step-by-step instructions on how to install a production test bed instance.
Guide: Updating the test bed for step-by-step instructions on how to update your test bed instance when new releases become available.
Guide: Defining your test configuration for step-by-step instructions on how to setup your test configuration in the test bed. Alternatively you can always refer to the Manage test configuration section from the test bed’s user guide.