Guide: Installing the test bed for development use

Track

Test bed operation

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.

Steps

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.

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:

version: '2.1'

volumes:
   gitb-repo:
   gitb-dbdata:

services:
   gitb-redis:
      image: redis:7.0.11
      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: 20
   gitb-srv:
      image: isaitb/gitb-srv
      container_name: itb-srv
      restart: unless-stopped
      environment:
       - gitb.messaging.server-ip-address=localhost
       - gitb.messaging.callbackURL=http://localhost:8080/itbsrv/MessagingClient
      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.

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

  • gitb-mysql is the test bed’s database.

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

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

../_images/DockerInstallation.png

Figure 1: Interactions and functions of test bed containers

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

gitb-srv

environment gitb.messaging.server-ip-address

The IP address that external systems may use to contact the test bed for certain types of direct messaging.

gitb-srv

environment gitb.messaging.callbackURL

The full address to access the test bed’s notification call-back interface. This must resolve to http://[gitb.messaging.server-ip-address]:8080/itbsrv/MessagingClient.

gitb-srv

ports

These represent the port mappings for the test bed on the local machine.

gitb-ui

environment THEME

Defines the UI theme to use. Use ec for a Commission theme or remove the property for a default GITB theme.

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 gitb-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).

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
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 you should 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 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 itb-ui issue 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 \
isaitb/gitb-mysql

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 \
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 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:

../_images/welcome2.png

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:

../_images/login2.png

Log in using the default administrator account of test@test.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:

../_images/home.png

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

Note

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 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:

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

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

  3. 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.

See also

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:

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: