Guide: Updating the test bed

Track

Test bed operation

This guide walks you through the process of updating a test bed instance to the latest release.

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 for development use or Guide: Installing the test bed for production use. 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 managed by the test bed team are automatically updated to latest releases. This guide is of interest 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.

In certain cases, activating and benefiting from new features may require providing new configuration parameters. If this is the case the parameters in question will be documented in detail in the test bed’s configuration properties and the 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.

Note

Backwards compatibility: New features are always introduced in a backwards compatible manner and can be enabled at any time during the test bed’s operation.

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 executing this command has no effect on your currently running test bed instance.

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

Warning

Updating to 1.13.0+: When updating from a release prior to 1.13.0 to a release starting from 1.13.0, the database container itb-mysql may take several minutes to update. This is because release 1.13.0 upgraded the internal MySQL database used by the Test Bed and the update process makes an automated (but time-consuming) upgrade. During this process the startup of the dependent itb-ui component will likely fail as itb-mysql is considered unhealthy. If this occurs make sure you do not stop itb-mysql before it completes. Instead you can monitor the upgrade status through its log and repeat later the docker-compose up -d command. Doing so will only attempt again to start itb-ui which will succeed once itb-mysql has completed its upgrade.

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

The current section applies if you are updating a development test bed instance that was installed directly using Docker commands (not Docker Compose). In this case 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 docker run commands as you did in the initial installation.

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

To check that the new release has been successfully installed you can verify the version number displayed on the test bed’s interface. To do this visit the test bed’s welcome page where you will find the version number 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 update your 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.

In terms of relevant guides, be sure to check: