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.
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.
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
docker-compose.yml file. The first step is to open a command prompt to the folder that contains
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 test bed’s configuration properties
and potentially 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.
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 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:
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-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¶
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. To do this visit the test bed’s welcome page on which you will see its current version 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 recreate your current installation.