Guide: Updating the test bed
Track |
---|
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.

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:
Guide: Installing the test bed for development use for step-by-step instructions on how to install a development test bed instance.
Guide: Installing the test bed for production use for step-by-step instructions on how to install a production test bed instance.