Guide: Updating the test bed¶
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.
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.
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
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
As an example consider a new parameter
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.
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:
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:
Once this command completes you can apply the new release by executing:
docker-compose up -d
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
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
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
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-ui containers. For
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
> 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.
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.
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.
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.