beacon-network-backend

Jakarta EE Platform 10

The implementation is developed and deployed on the WildFly 30.0.0 server and is based on Jakarta RESTful Web Services 3.0 API (JAX-RS 3.0).

Beacon v2 Java implementation

The implementation uses Beacon v2 Java beacon-framework model classes.

Installation

Docker Image (recommended)

This repository is configured to automatically generate docker images on release tags ('vX.Y.Z'). The image is based on official WildFly image that is extended with PostgreSQL driver and predeployed Beacon Network application.

To have an easy deployment, go to the docker folder and run docker compose:

docker-compose up -d

Manual installation

Apache Maven build system

The build process is based on Apache Maven.

Compiling:

git clone https://github.com/elixir-europe/beacon-network-backend.git
cd beacon-network-backend
mvn install

This must create beacon-network-v2-x.x.x.war (Web application ARchive) application in the /target directory. Alternatively, you can find this file in the Barcelona Supercomputing Center's maven repository.

WilfFly server

WildFly is a free opensource JEE server and may be easy downloaded from it's website: http://wildfly.org/.
Nevertheless, the sever requires some configuration which in a case of docker image is done by the Dcokerfile recipe.

The implementation relies on JSON-B 3.0 Eclipse Yasson^TM implementation, but requires yet unreleased 3.0.4 version yasson-3.0.4-SNAPSHOT.jar. Once WildFly is updated to the 3.0.4 version of Yasson^TM this step would be unneccessary.

The Beacon Network logging is implemented using Jakarta Persistence 3.1 and relies on PostgreSQL database. The server must be pre-configured for the PostgreSQL and the PosgreSQL JDBC driver must be intalled into the WildFly (docker image recipe does this job).

The deployment is as simple:

# Copy .war file to wildfly
cp target/beacon-network-v2-x.x.x.war $WILDFLY_HOME/standalone/deployments/
# Run the application server
./$WILDFLY_HOME/bin/standalone.sh

Configuration

There are three default configuration files in the /BEACON-INF directory:

• configuration.json - standard beacon configuration file: beaconConfigurationResponse.json
• beacon-info.json - standard beacon information file: beaconInfoResponse.json
• beacon-network.json - Json Array of backed Beacons' endpoints

The example of the beacon-network.json:

[
  "https://beacons.bsc.es/beacon/v2.0.0",
  "https://ega-archive.org/test-beacon-apis/cineca"
]

Note that the Web application ARchive (WAR) is just a usual ZIP file so one can edit these configurations manually without the need to rebuild the application. The same with Docker, it is automatically updated with new beacons.

It is also possible to define external directory for the configuration.

export BEACON_NETWORK_CONFIG_DIR=/wildfly/BEACON-INF

When the BEACON_NETWORK_CONFIG_DIR is set, the aggregator monitors the $BEACON_NETWORK_CONFIG_DIR/beacon-network.json to dynamically update the configuration.
It also looks (but not actively monitoring) the $BEACON_NETWORK_CONFIG_DIR/beacon-info.json so deployers may change the beacon identifier and other metatada.

There are several timeouts that may be configured via environment variables:

• BEACON_NETWORK_REFRESH_METADATA_TIMEOUT - timeout in minutes (default 60 min.) Beacon Network reloads metadata of the backed Beacons.
• BEACON_NETWORK_DISCARD_REQUEST_TIMEOUT - timeout in seconds (default 5 sec.) after which the response from a Beacon is discarded.
• BEACON_NETWORK_REQUEST_TIMEOUT - timeout in seconds (default 600 sec.) after which the request to the Beacon is cancelled.

Note that although responses that take more than BEACON_NETWORK_DISCARD_REQUEST_TIMEOUT are discarded (not included in the Beacon Network response), they are not cancelled. If a long answering Beacon responds before the BEACON_NETWORK_REQUEST_TIMEOUT, the result still may be logged.

SQL Database

The Beacon Network Aggregator uses Jakarta Persistence 3.1 for logging. The connection is defined in persistence.xml. Although the Aggregator may be used with any SQL database, it is configured to be used with PostgreSQL database.

The application provides simple SQL logging which level may be confirured via BEACON_NETWORK_LOG_LEVEL environment variable.
The possible values are "NONE", "METADATA", "REQUESTS", "RESPONSES", "ALL"

• "NONE" : No logging at all.
• "METADATA" : Only backed beacons' metadata is logged (good for debugging).
• "REQUESTS" : Beacon Network Request quieries are logged. It also logs response codes (but not the data).
• "RESPONSES" : Logs all Requests with Responses as well as possible error messages.
• "ALL" : Maximum logging level. Currently same as "RESPONSES"