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

volumes:
   gitb-repo:
   gitb-dbdata:

services:
   gitb-redis:
      image: redis:7.2.5
      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:
       - 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.

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 5: 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/CALLBACK_ROOT_URL`	The base address for test engine call-backs.
`gitb-srv`	`ports`	This is the port mapping for the test bed’s test engine 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.
`gitb-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 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 gitb-srv ...
Creating gitb-redis ...
Creating gitb-mysql ...
Creating gitb-srv
Creating gitb-redis
Creating gitb-srv ... done
Creating gitb-ui ...
Creating gitb-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. gitb-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 gitb-srv and gitb-ui. For gitb-srv issue docker logs -f gitb-srv for which you should see output completing as follows:

> docker logs -f gitb-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 gitb-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.2.5

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

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

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 Docker

Step 2: Define the test bed’s configuration

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