The current project contains the main application components that are used by the Interoperability Test Bed. These are:
- The test engine, responsible for executing test cases and reporting their progress and outcome.
In terms of Docker images, this component represents the
gitb-srvimage. - The frontend, responsible for the Test Bed's user interface and its test, user, and configuration
management features. In terms of Docker images, this component represents the
gitb-uiimage.
In the subsequent sections each of these components will be refered to using their Docker image names
(gitb-srv and gitb-ui).
Both gitb-srv and gitb-ui are Java-based applications. Specifically, gitb-srv is packaged
as a Spring Boot application using Akka as its primary internal framework, whereas gitb-ui
is developed in Scala and uses the Play Framework.
The frontend of the gitb-ui component is an Angular app developed in TypeScript, and is managed in terms
of scaffolding and build using Angular CLI.
To build and run the Test Bed's components you need to have the following tools:
- JDK 11+, used as the base platform for both
gitb-srvandgitb-ui. - Maven 3+, used to build
gitb-srv. - SBT 1.3.13+, used to build
gitb-ui. - NPM version 6.14+, used to build the frontend app of
gitb-ui.
Although not mandatory, the proposed IDE to use is IntelliJ, and VS Code for gitb-ui's Angular app.
The focus of this README file is the gitb-srv and gitb-ui components. To run a complete Test Bed instance
you will also require at least:
- A MySQL database (version 5.*) for its persistence.
- A REDIS instance for the caching of user sessions.
Both these instances are set up separately (e.g. via Docker) environment. These can be set-up from Docker as follows:
- MySQL:
docker run --name gitb-mysql -p 3306:3306 -d isaitb/gitb-mysql - REDIS:
docker run --name gitb-redis -p 6379:6379 -d redis:6.0.8
The main configuration file of interest is application.conf from gitb-ui although this never needs
to be adapted directly. All properties can be set through environment variables, provided either via Docker
or through the IDE used for development.
The full listing and documentation of properties is available at https://www.itb.ec.europa.eu/docs/guides/latest/installingTheTestBedProduction/index.html#configuration-properties.
Follow these steps to build and run the application components for development purposes.
To build and run the gitb-srv component carry out the following steps:
- From folder
gitbrunmvn clean install -DskipTests=true. - Create a run configuration in your IDE as follows (or set up outside your IDE). The run configuration
can be defined in one of two ways:
- As a Java Application (best): Set class
Applicationfrom thegitb-testbed-servicemodule as your entry point. This is the best approach as it allows direct debugging without extra configuration. - Via Maven: Run
mvn spring-boot:runfrom thegitb-testbed-servicemodule.
- As a Java Application (best): Set class
- Adapt your run definition's environment variables to add the following:
remote.testcase.repository.url= http://localhost:9000/repository/tests/:test_id/definitionremote.testresource.repository.url= http://localhost:9000/repository/resource/:test_id/:resource_id
Note that defining a run configuration is something specific. If running outside an IDE you can follow either approach but ensure that the environment variables are correctly set up.
To build and run the gitb-ui component carry out the following steps:
- From the
gitb-uifolder issuesbt compile. - Define in your IDE a run configuration as a sbt application to run
sbt run. - Set environment variables as needed. For example set
THEME = ecfor a EC-themed UI.
The next step is to choose how to build and run the Angular UI application. Its resources are defined in
the gitb-ui/ui folder and its build is managed by Angular CLI. You have two options on how to work with
the Angular app - choose the preferred approach for you from the two following sections. As a common first
step regardless of the approach you choose you need to issue npm install from folder gitb-ui/ui.
Developing with EU Login enabled: In case you are developing with EU Login enabled (i.e. against a local EU Login test instance), you need to ensure that the following environment variables are set:
SESSION_SECUREset tofalseSESSION_COOKIE_NAMEset toITB_SESSION.
Failure to set these properties will result in session cookies never getting served over HTTP, resulting in endless authentication loops. The alternative is to test over HTTPS via a local SSL-enabled proxy (e.g. a local nginx server with a self-signed server certificate).
Using this approach you build the Angular app using Angular CLI but access it through the Play application. To do this:
- From
gitb-ui/uiissuenpm run build. This will build the app and copy it under the Play application'sassetsfolder. To rebuild automatically for any changes usenpm run build:dev. - Access the application by first going to the Play application's welcome page at http://localhost:9000. Once you click any of the login options the Angular app will be launched.
- Once any part of the Angular app is rebuilt you will need to refresh the browser page to see changes.
When to use this approach: Using this approach mirrors exactly how the application will run in production. In addition, you may need to use this approach to effectively test aspects that require interaction with the Play application. These include:
- Testing with EU Login enabled (as EU Login's callback returns to the Play application).
- Testing the different login options (e.g. register, demos, confirm role assignment).
Using this approach you build and serve the Angular app using Angular CLI. In this scenario the Play application is only used through its REST API which the Angular app proxies and uses. To use this approach:
- Only once from
gitb-ui/uiissuenpm run build. This is needed to put in place static resources used by the Angular app (most notably tinymce styles). - From
gitb-ui/uiissuenpm start. This reloads the app upon detected changes. - Access the application at http://localhost:4200 (this will be automatically opened for you).
When to use this approach: This approach is the most efficient as it allows use of the lightweight CLI server and provides automatic refresh for build changes. The problem with this approach is that it cannot cover cases where you need to test interactions with the Play application (e.g. when EU Login is used for authentication). Having said this however, you can still use this after you have authenticated using the Play application given that authentication cookies are shared.
Follow these steps to make the components' production builds.
- From the current (root) folder issue
mvn clean install -DskipTests=true - Copy file
gitb-testbed-service/target/itbsrv.warto a separate folder to build its Docker image. - Use Dockerfile
etc/docker/gitb-srv/Dockerfilefrom the same folder to build the image.
- From the
gitb-uifolder issuesbt clean dist. This builds all Play code and automatically calls the required prod build target from its Angular app. - Unzip the contents of the
gitb-ui/target/universal/gitb-1.0-SNAPSHOT.ziparchive to a separate folder. The name of the resulting unzipped folder should begitb-ui. - Use the Dockerfile
etc/docker/gitb-ui/Dockerfilefrom the same folder to build the image.
Once a complete Test Bed instance has been setup, either in development or production mode, access using the default Test Bed administrator account as follows:
- Go to http://localhost:9000.
- Click on the login button.
- Authenticate using
test@test.comwith a password oftest.