Guide: Updating the test bed

Track Test bed operation

This guide walks you through the process of updating test bed versions.

What you will achieve

At the end of this guide you will have updated a test bed instance to the latest test bed release. The update process assumes that your target instance has been installed using Docker as described in Guide: Installing the test bed. Updating a test bed installation that is not based on Docker is possible but is out of scope for the current guide.

Note

Automatically applying new releases: Production test bed instances (i.e. ones that are being used for actual testing) are typically automatically updated to the latest release as part of an organisation’s agreement with the ISA² test bed team. This guide would thus be interesting to you if you are managing your own instance or if you are looking to update a local development installation.

What you will need

  • About 5 minutes.
  • A text editor (if new configuration is needed).
  • A web browser.
  • A working Docker-based test bed installation.
  • Command line access to the machine hosting the test bed.
  • Access to the internet (from the host machine).

How to complete this guide

Completing the update steps will be done by issuing commands on a command line interface. All commands are provided and explained in each relevant step.

Steps

Carry out the following steps to complete this guide.

Step 1: Verify your test bed’s configuration file

All information on your test bed installation, in terms both of Docker properties as well as test bed configuration, is located in the test bed’s docker-compose.yml file. The first step is to open a command prompt to the folder that contains docker-compose.yml.

Changes to the test bed are always introduced in a backwards-compatible manner but in certain cases activating and benefiting from new features may require providing certain configuration parameters. If this is the case the parameters in question will be documented in detail in the relevant online release notes. Setting such parameters is always done by updating the docker-compose.yml file.

As an example consider a new parameter ACTIVATE_NEW_FEATURE for gitb-ui (the test bed’s user interface) that could be introduced as follows:

version: '2'
    ...
services:
    ...
    gitb-ui:
        ...
        environment:
         - THEME=ec
         - ACTIVATE_NEW_FEATURE=true
         ...

If you do have any new parameters to configure do so by editing your docker-compose.yml file with your preferred text editor.

Step 2: Get the latest release

To get the latest test bed release open a command prompt to the folder containing the docker-compose.yml file and issue the following command:

docker-compose pull

This command will check the Docker Hub for each of the test bed’s components (Docker images) and will proceed to download newer versions as needed. Note that running this command has no effect on your currently running test bed.

Step 3: Apply the release

Applying the release is a two-step process. First remove the existing test bed containers by executing:

docker-compose down

Once this command completes you can apply the new release by executing:

docker-compose up -d

To ensure the test bed is successfully updated check the logs of the itb-srv and itb-ui containers. For itb-srv issue docker logs -f itb-srv for which you should see in the end:

> docker logs -f itb-srv

...
12-Sep-2018 12:52:41.159 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in 18918 ms

Exit the log display using CTRL-C. Then check itb-ui by issuing docker logs -f itb-ui for which the output should complete as follows:

> docker logs -f itb-ui

...
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 CTRL-C. Your test bed should now be online and updated to the latest release.

Note

Installing a new release from scratch: Issuing docker-compose down removes your test bed’s containers but keeps all its data. To completely uninstall the test bed before applying the new release use docker-compose down -v.

Alternative update using Docker commands

In case your test bed was installed using Docker commands directly and not via Docker Compose, you need to use the Docker command line interface to carry out the update. Open a command prompt and issue:

docker pull isaitb/gitb-ui:latest

docker pull isaitb/gitb-srv:latest

Once these commands complete you will have downloaded the latest versions of the test bed’s software components. The next step is to stop and remove the current ones by issuing:

docker stop gitb-ui gitb-srv

docker rm gitb-ui gitb-srv

Finally, issue the following commands to create and run the new containers based on the latest image versions:

docker run --name gitb-srv --net=gitb-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:latest

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

Remember that before issuing these commands you would need to replicate on the command line the configuration parameters you had previously used (e.g. for gitb.messaging.server-ip). In addition you would need to adapt, as needed for the new release, the containers’ environment properties (passed using the -e flag). This is one reason why managing your installation with Docker Compose is simpler.

Step 4: Verify the new release

An extra step you can take to check that the new release has been successfully installed is to check the version number from the test bed’s interface. Go to your test bed’s login page on which you will see its current version in the bottom right corner.

../_images/login_version.png

Summary

Congratulations! You have just updated your test bed to the latest version. In doing so you used Docker to download the test bed’s latest component versions that you then used to recreate your current installation.

See also

For more information on the Docker and Docker Compose tools, commands and properties used in this guide, check out the Docker online documentation.