rwthacis/las2peer-activity-tracker repository overview

⁠las2peer-ActivityTracker

⁠Idea

las2peer-ActivityTracker is a microservice to provide activity information for las2peer services. The service works together with all kinds of microservices.

The activity tracker response to HTTP or (las2peer) p2p requests and can fetch activity objects from the origin microservice which created an activity. This service has also build-in MQTT support, so that all new activities will get publish to an MQTT broker of your choice. To enable MQTT publish please provide the MQTT information in the configuration file.

We also provide a modern webcomponent frontend for this service which you can find on Github⁠.

The service is under development. You can participate by creating pull requests or by discussing ideas and requirements inside Requirements-Bazaar⁠.

More information about our microservice ecosystem is explained in our Requirements-Bazaar wiki on Github⁠.

⁠Service Documentation

We use Swagger⁠ for documenting this microservice. You can use Swagger UI⁠ to inspect the API. You can inspect the API documentation of our live (master branch) instance an our beta (develo branch) with our Swagger UI instance⁠.

API documentation endpoint:

• baseURL/activities/swagger.json

⁠Technology

The activity tracker is built on Java technologies. As a service framework we use our in-house developed las2peer⁠ project. For persisting our data we use MySQL database and jOOQ to access it. User input validation is done using Jodd Vtor library and for serializing our data into JSON format, we use the Jackson library. As MQTT client we use Eclipse Paho.

⁠Dependencies

In order to be able to run this service project the following components should be installed on your system:

• JDK (min v1.8) + Java Cryptography Extension (JCE)
• MySQL 5.7
• Gradle to build

⁠How to set up the database

1. git clone this repo
2. To configure your database access look at the Configuration⁠ section
3. Create a new database called reqbaztrack, possibly with UTF-8 collation
4. Compile the project with ./gradlew build
5. Run ./gradlew flywayMigrate to create your db schema or migrate to a newer version while updating your service
6. If you need sample data import the file etc/add_activitytracker_demo_data.sql into your database.

⁠Configuration

You need to configure the service to your own specific environment. Here is the list of configuration variables:

etc/de.rwth.dbis.acis.activity.service.ActivityService.properties:

• dbUserName: Database username, which will be used to access the database
• dbPassword: Database user password, which will be used to access the database
• dbUrl: JDBC Connection string to access the database
• baseURL: Base URL this service runs on
• mqttBroker: MQTT Broker, if this field is set it enables MQTT publish of new activities (optional).
• mqttUserName: MQTT username to publish to broker, if this field is set MQTT use username and password. If not it MQTT doe not use authorize to broker (optional).
• mqttPassword: MQTT password to publish to broker (optional)
• mqttOrganization: Your organisation name, used as first channel description in MQTT (optional)

For other configuration settings, check the las2peer⁠ project.

⁠Build

For build management we use Gradle. To build the cloned code, please use a console/terminal open the projects root directory and run:

• ./gradlew build

Make sure your database settings are configured correctly in the settings.gradle since jooq requires the applied database schema to generate the respective code. Flyway will automatically take care of applying the necessary database schema migrations.

⁠How to run

1. First please make sure you have already set up the database⁠
2. Make sure your config settings⁠ and gradle settings are properly set.
3. Build⁠
4. Open a console/terminal window and navigate to the bin directory
5. Run the start_network.bat or start_network.sh script

⁠How to run using Docker

First build the image:

docker build . -t activity-tracker

Then you can run the image like this:

docker run -e MYSQL_USER=myuser -e MYSQL_PASSWORD=mypasswd -p 8080:8080 -p 9011:9011 activity-tracker

Replace myuser and mypasswd with the username and password of a MySQL user with access to a database named reqbaztrack. By default the database host is mysql and the port is 3306. The REST-API will be available via http://localhost:8080/activities⁠ and the las2peer node is available via port 9011.

In order to customize your setup you can set further environment variables.

⁠Node Launcher Variables

Set las2peer node launcher options⁠ with these variables. The las2peer port is fixed at 9011.

⁠Service Variables

See configuration⁠ for a description of the settings.

⁠Web Connector Variables

Set WebConnector properties⁠ with these variables. httpPort and httpsPort are fixed at 8080 and 8443.

⁠Other Variables

⁠Custom Node Startup

If the variables are not sufficient for your setup you can customize how the node is started via arguments after the image name. In this example we start the node in interactive mode:

docker run -it -e MYSQL_USER=myuser -e MYSQL_PASSWORD=mypasswd activity-tracker startService\(\'de.rwth.dbis.acis.activitytracker.service.ActivityTrackerService@0.6.0\', \'Passphrase\'\) startWebConnector interactive

Inside the container arguments are placed right behind the launch node command:

java -cp lib/* i5.las2peer.tools.L2pNodeLauncher -s service -p ${LAS2PEER_PORT} <your args>

⁠Volumes

The following places should be persisted in volumes in productive scenarios:

Do not forget to persist you database data

⁠Troubleshooting & FAQ

• I get Java encryption errors: Did you install Java Cryptography Extension?
• I can not run the start script: Check if you have OS permission to run the file.
• The service does not start: Check if all jars in the lib and service folder are readable.
• The start script seems broken: Check if the start script has the correct encoding. If you ran the service on Unix use dos2unix to change the encoding.
• To enable MQTT publish of new activities set mqttBroker and mqttOrganization in property file.