Guide: Installing the test bed

Track Test bed operation

This guide walks you through the process of installing a new test bed instance.

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 which you can freely experiment before finalising the test suites and test services needed by your project.
  • Your project’s online test bed instance that will be used by your users to test.

In all cases the installation process is largely the same and is designed to be simple, fast and self-contained. For this purpose the advised approach is to use Docker that greatly simplifies installation, management and patching. Not using Docker is possible but this would require the separate installation of third party software and building the core test bed components from source. This alternative installation approach is significantly more complex and is out of scope for the current guide.

Note

Using the ISA² test bed: Installing one or more test bed instances locally is advised as a local development environment on which you have full control. However, when it comes to launching your conformance testing services online, you would typically be using the shared ISA² test bed at https://www.itb.ec.europa.eu/itb so that you don’t need to be concerned with hosting, monitoring and support. You may of course choose to run your own test bed instance online in case you have specific constraints (e.g. internal network access, use of sensitive data) or if you simply want to manage all aspects of your testing services yourself.

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. Storage-wise you may get started with a lot less (even 5 GB) but it is good to foresee sufficient space to store test suites, resources, test reports etc. 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 typically involves executing commands on a command line interface.

The examples that will be used are geared towards a development installation. When further configuration options exist that are more pertinent to production use, these will be highlighted and explained.

Steps

Carry out the following steps to complete this guide.

Step 1: Install Docker

The first step is to ensure you have Docker installed on the machine you will use to host the test bed. If you already have Docker then ensure it is at least at version 17.06.0.

If this is not the case then follow Docker’s online installation instructions. As a first step here you will be presented with an overview of Docker’s different versions (community or enterprise edition) and supported operating systems. To help you better navigate this part of the documentation take into account the following pointers:

  • The test bed runs both on Docker CE (Community Edition) and Docker EE (Enterprise Edition).
  • Running on Linux and recent versions of Windows (minimum Microsoft Windows 10 Professional or Enterprise 64-bit) or macOS (minimum macOS El Capitan 10.11) is simple, as Docker is natively supported.
  • Running on older versions of Windows or macOS requires Docker to be installed in a virtual machine. The setup and use of this is automatically handled by installing the Docker Toolbox.

Once complete, you will be able to test your Docker installation using the docker --version command that should provide output as follows:

> docker --version

Docker version 18.03.0-ce, build 0520e24

Docker uses an online repository of container images called the Docker Hub from which it pulls all images needed to install components. To ensure you can correctly connect to this you can install and run Docker’s hello-world image as follows:

> docker run hello-world

docker : Unable to find image 'hello-world:latest' locally
...

latest:
Pulling from library/hello-world
ca4f61b1923c:
Pulling fs layer
ca4f61b1923c:
Download complete
ca4f61b1923c:
Pull complete
Digest: sha256:97ce6fa4b6cdc0790cda65fe7290b74cfebd9fa0c9b8c38e979330d547d22ce1
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

Note

Production installation: If you are installing the test bed for production use you need to be aware of how it handles ports. The test bed opens dynamically ports on its host machine for simulated test case actors which can be time and memory consuming. To address this it is recommended to run Docker with hairpin NAT enabled, rather than relying on a per-port userland proxy, by setting the following value in Docker’s configuration file (located at e.g. /etc/default/docker for an Ubuntu distribution):

DOCKER_OPTS="--userland-proxy=false"

If you are intending to run the test bed for demo purposes then you can skip this configuration step.

Step 2: Install Docker Compose

Docker Compose is a tool for defining and running multi-container Docker applications (such as the test bed). Depending on the version of Docker you have and your operating system you may already have Docker Compose installed. Check this by issuing the docker-compose --version command that should give output as follows:

> docker-compose --version
docker-compose version 1.16.1, build 6d1ac219

If you don’t have Docker Compose already installed follow its installation guide.

Step 3: 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'

volumes:
   gitb-repo:
   gitb-dbdata:

services:
   gitb-redis:
      image: redis:3.0.7
      container_name: itb-redis
      restart: unless-stopped
   gitb-mysql:
      image: isaitb/gitb-mysql
      container_name: itb-mysql
      restart: unless-stopped
      environment:
       - MYSQL_ROOT_PASSWORD=root
      volumes:
       - gitb-dbdata:/var/lib/mysql
   gitb-srv:
      image: isaitb/gitb-srv
      container_name: itb-srv
      restart: unless-stopped
      environment:
       - gitb.messaging.server-ip-address=192.168.99.100
       - gitb.messaging.callbackURL=http://192.168.99.100:8080/itbsrv/MessagingClient
      ports:
       - "8080-8180:8080-8180"
   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
       - gitb-mysql
       - gitb-srv

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. 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-mysql environment MYSQL_ROOT_PASSWORD This is the password for the root database user. In the example this is set to root but for a non-development environment you would typically want to set this to an appropriate value.
gitb-srv environment gitb.messaging.server-ip-address The IP address that external systems may use to contact the test bed.
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. The reason this is configurable is because this may be mapped differently at reverse proxy level.
gitb-srv ports these represent the port mapping for the test bed on the local machine. If running in production you may choose to increase these up to 8080-8380:8080-8380.
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.

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. 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: Installing an on-premise instance of the test bed for production use would typically require further advanced configuration that is by default deactivated. If you are in the process of installing such an instance you will want to consider the full listing of configuration properties (see Advanced configuration properties).

Step 4: 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
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 /gitb-repository --name itb-repo ubuntu

docker run --name itb-mysql --net=itb-net -p 3306:3306 -d --restart=unless-stopped \
-e MYSQL_ROOT_PASSWORD=root \
isaitb/gitb-mysql

docker run --name itb-redis --net=itb-net -d --restart=unless-stopped redis:3.0.7

docker run --name itb-srv --net=itb-net -p 8080-8180:8080-8180 \
-e gitb.messaging.server-ip-address=192.168.99.100 \
-e gitb.messaging.callbackURL=http://192.168.99.100: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 5: Test your installation

To test your installation you can try to log into its user interface using the default test bed administrator account.

Open a browser window and navigate to http://DOCKER_HOST:9000. On Linux and latest Windows and macOS versions the DOCKER_HOST should actually be your localhost. If running on older versions of Windows or macOS that use a virtual machine to run Docker, the DOCKER_HOST would match the virtual machine’s IP address (typically 192.168.99.100). 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. 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.

Step 6: 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 Docker container. 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 log -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).

Summary

Congratulations! You have now completed your test bed installation. 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.

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:

References

This section contains additional references linked to this guide.

Advanced configuration properties

When installing a test bed instance for production purposes you need to consider additional aspects such as security, proxying, and email sending. In all cases such properties are configured as environment variables in the test bed’s docker-compose script. All such environment properties are defined in the gitb-ui component.

The following table summarises the available properties, their purpose, supported values and defaults.

Property Category Description Default
TESTBED_HOME_LINK General The full link to use to return back to the welcome page if an error occurs (may need to be adapted to accomodate reverse proxy settings). /
SAVED_FILE_MAX_SIZE General The maximum size (in KBs) for uploaded files that are to be persisteb in the test bed’s database (not email attachments). 1024
TSA_SERVER_ENABLED Conformance certificates Set to true to enable trusted timestamp generation using a TSA server for signatures of conformance certificates. false
TSA_SERVER_URL Conformance certificates The URL of the TSA server for signature timestamp generation. https://freetsa.org/tsr
PROXY_SERVER_ENABLED Proxy Set to true to define a proxy for outgoing connections from the test bed. false
PROXY_SERVER_HOST Proxy The proxy server’s host.  
PROXY_SERVER_PORT Proxy The proxy server’s port.  
PROXY_SERVER_AUTH_ENABLED Proxy Set to true in case the proxy server requires authentication. false
PROXY_SERVER_AUTH_USERNAME Proxy The username to use when authenticating against the proxy server.  
PROXY_SERVER_AUTH_PASSWORD Proxy The password to use when authenticating against the proxy server.  
AUTHENTICATION_COOKIE_PATH Authentication The cookie path to set for generated session cookies (should be adapted to accommodate reverse proxy mappings). /
AUTHENTICATION_SSO_ENABLED Authentication Whether or not the test bed will use EU Login as an SSO solution. false
AUTHENTICATION_SSO_IN_MIGRATION_PERIOD Authentication Whether or not features relevant to migrating from a non-SSO to an SSO-enabled environment should be activated. false
AUTHENTICATION_SSO_LOGIN_URL Authentication The complete URL of the EU Login service to redirect to for authentication.  
AUTHENTICATION_SSO_CALLBACK_URL Authentication The complete URL of the test bed instance to redirect back to. This should be set to the test bed’s full address postfixed with /callback.  
AUTHENTICATION_SESSION_MAX_IDLE_TIME Authentication The maximum time (in seconds) that a session will be kept alive if there is no activity. 3600
AUTHENTICATION_SESSION_MAX_TOTAL_TIME Authentication The maximum overall time (in seconds) that a session is allowed to exist without re-authentication. A value of -1 disables this. -1
ANTIVIRUS_SERVER_ENABLED Antivirus Set to true to virus scan user-uploaded files using a ClamAV service. false
ANTIVIRUS_SERVER_HOST Antivirus The ClamAV server’s hostname.  
ANTIVIRUS_SERVER_PORT Antivirus The TCP port the ClamAV server is listening on for scan requests.  
ANTIVIRUS_SERVER_TIMEOUT Antivirus The timeout (in milliseconds) after which to fail if the antivirus server fails to respond. This is disabled by using 0 0
MASTER_PASSWORD Encryption The master password to use to encrypt sensitive values in the test bed’s database.  
HMAC_KEY Encryption The key to use to sign request digests sent between the gitb-ui and gitb-srv components.  
HMAC_WINDOW Encryption The maximum window (in milliseconds) in which to accept exchanged requests sent between gitb-ui and gitb-srv. 10000
USERGUIDE_OU User guide The address of the user guide for organisation users. https://www.itb.ec.europa.eu/docs/itb-ou/latest
USERGUIDE_OA User guide The address of the user guide for organisation administrators. https://www.itb.ec.europa.eu/docs/itb-oa/latest
USERGUIDE_CA User guide The address of the user guide for community administrators. https://www.itb.ec.europa.eu/docs/itb-ca/latest
USERGUIDE_TA User guide The address of the user guide for test bed administrators. https://www.itb.ec.europa.eu/docs/itb-ta/latest
SURVEY_ENABLED Satisfaction survey Set to false to disable the link to the test bed’s satisfaction survey. true
SURVEY_ADDRESS Satisfaction survey The address of the test bed’s satisfaction survey. https://ec.europa.eu/eusurvey/runner/itb
DEMOS_ENABLED Demos Whether links to demo scenarios should be displayed. false
DEMOS_ACCOUNT Demos The database user ID of a specific test bed user to be used as a demo user.  
REGISTRATION_ENABLED General Whether or not self-registration for public communities is allowed for this test bed instance. true
GUIDES_EULOGIN_USE Guides The full address for the guide on how to use EU Login. https://www.itb.ec.europa.eu/docs/guides/latest/usingEULogin
GUIDES_EULOGIN_MIGRATION Guides The full address for the guide on how to migrate to EU Login. https://www.itb.ec.europa.eu/docs/guides/latest/migratingToEULogin
EMAIL_ENABLED Email Set to true to enable emails to be sent to the support team from within the test bed. false
EMAIL_FROM Email The “FROM” address for support emails (e.g. Contact Form <contact@itb.ec.europa.eu>). Contact Form <contact@itb.ec.europa.eu>
EMAIL_TO Email The support team’s email address. DIGIT-ITB@ec.europa.eu
EMAIL_SMTP_HOST Email The SMTP server’s host.  
EMAIL_SMTP_PORT Email The SMTP server’s port.  
EMAIL_SMTP_AUTH_ENABLED Email Set to true if authentication is required by the SMTP server (if EMAIL_ENABLED is true). false
EMAIL_SMTP_AUTH_USERNAME Email The username to use when authenticating against the SMTP server.  
EMAIL_SMTP_AUTH_PASSWORD Email The password to use when authenticating against the SMTP server.  
EMAIL_ATTACHMENTS_MAX_COUNT Email The maximum number of attachments allowed to include in contact form submissions. Setting this to 0 or negative disables contact form attachments. 5
EMAIL_ATTACHMENTS_MAX_SIZE Email The maximum total size (in MBs) for attachments. 5
EMAIL_ATTACHMENTS_ALLOWED_TYPES Email A comma-separated list of MIME types corresponding to the types of files that are allowed as attachments in contact form submissions. text/plain,image/gif,image/png,image/jpeg,application/pdf,application/xml,text/xml

Note

EU Login integration: Commission-hosted test bed instances are eligible for integration with EU Login, the European Commission’s central authentication service. To do this, apart from adapting the test bed’s configuration you will also need to coordinate with the EU Login helpdesk to register your instance as an accepted service.

Note that the antivirus-related properties listed above (ANTIVIRUS_SERVER_*) consider use of the popular ClamAV antivirus server. An ideal setup for this is to install a self-updating ClamAV instance using Docker that is placed on the same network as the other test bed containers.

The following docker-compose.yml example provides a complete setup using several of the above properties that could be used for development purposes. This uses a mailcatcher instance to simulate an SMTP server and a ClamAV instance for virus scanning (here):

version: '2'

volumes:
    gitb-repo:
    gitb-dbdata:

services:
    gitb-redis:
        image: redis:3.0.7
        container_name: itb-redis
        restart: unless-stopped
    gitb-mysql:
        image: isaitb/gitb-mysql
        container_name: itb-mysql
        restart: unless-stopped
        environment:
         - MYSQL_ROOT_PASSWORD=root
        volumes:
         - gitb-dbdata:/var/lib/mysql
    gitb-srv:
        image: isaitb/gitb-srv
        container_name: itb-srv
        restart: unless-stopped
        environment:
         - gitb.messaging.server-ip-address=192.168.99.100
         - gitb.messaging.callbackURL=http://192.168.99.100:8080/itbsrv/MessagingClient
        ports:
         - "8080-8180:8080-8180"
    gitb-ui:
        image: isaitb/gitb-ui
        container_name: itb-ui
        restart: unless-stopped
        ports:
         - "9000:9000"
        environment:
         - THEME=ec
         - EMAIL_ENABLED=true
         - EMAIL_FROM=contact@itb.ec.europa.eu
         - EMAIL_TO=DIGIT-ITB@ec.europa.eu
         - EMAIL_SMTP_HOST=gitb-smtp
         - EMAIL_SMTP_PORT=1025
         - EMAIL_SMTP_AUTH_ENABLED=false
         - ANTIVIRUS_SERVER_ENABLED=true
         - ANTIVIRUS_SERVER_HOST=gitb-antivirus
         - ANTIVIRUS_SERVER_PORT=3310
        volumes:
         - gitb-repo:/gitb-repository
        depends_on:
         - gitb-redis
         - gitb-mysql
         - gitb-srv
         - gitb-smtp
         - gitb-antivirus
    gitb-smtp:
        image: schickling/mailcatcher
        container_name: itb-smtp
        restart: unless-stopped
        ports:
         - "1080:1080"
    gitb-antivirus:
        image: mkodockx/docker-clamav
        container_name: itb-antivirus
        restart: unless-stopped