The Anatomy of the UBOS Personal Data Mesh web application

/docs/developers/reference-mesh/anatomy-webapp/

Overview

The UBOS Personal Data Mesh has many components; its most important one is the web application through which the user interacts with their personal data. Here we describe its overall structure.

A daemon behind Apache

When a device running the UBOS Personal Data Mesh web application receives an incoming HTTP request, this HTTP request is handled by the Apache web server (which acts as a reverse proxy).

This has several reasons, including:

  • it enables the user run run additional web applications on the same device, such as at different virtual hostnames;
  • SSL/TLS certificate management can be performed using Apache, including, for example, automatic Letsencrypt certificate renewals.

This reverse proxy configuration is set up automatically by UBOS Linux when the UBOS Personal Data Mesh is deployed.

The actual UBOS Personal Data Mesh daemon is a systemd service, created with the Apache Commons JSVC framework. This framework was specifically created for long-running Java daemons, such as this one.

The UBOS Personal Data Mesh systemd service is usually called diet4j-jsvc@<NNNN>.service, where <<NNNN>> is a random hex number (the AppConfigId) of the UBOS Linux AppConfiguration). To check whether it is running:

% sudo systemctl | grep diet4j

and, with the appropriate <NNNN>:

% system systemctl status diet4j-jsvc@<NNNN>.service

The diet4j module framework

The UBOS Personal Data Mesh uses the diet4j java module framework. This makes it possible to develop, and deploy, and run, the UBOS Personal Data Mesh in a modular fashion that is more suitable for the UBOS Personal Data Mesh requirements than other module frameworks (like OSGI).

The systemd service configuration invokes the JSVC excutable, which then runs diet4j’s “main program” for JSVC services in class org.diet4j.jsvc.Diet4jDaemon. You can see this in the ExecStart section of the systemd service file:

% systemctl cat diet4j-jsvc@.service

which contains the snippet:

ExecStart=/usr/bin/jsvc \
        ...
        -cp /usr/lib/java/org/diet4j/diet4j-jsvc/${DIET4J_VERSION}/diet4j-jsvc-${DIET4J_VERSION}.jar \
        ...
        org.diet4j.jsvc.Diet4jDaemon \
        $DIET4J_ARGS

The diet4j module framework, in turn, follows the instructions in file /etc/diet4j/diet4j-jsvc-<NNNN>.env, which define a few environment variables, but also the main diet4j properties in file /etc/diet4j/diet4j-jsvc-<NNNN>/ubos-mesh-underbars-mysql.properties

If you look at this file, you will some qualified Java properties used to determine which modules to load, and how to configure them, like this:

diet4j!module=net.ubos.underbars.mysql ubos-mesh-model-amazon ubos-mesh-model-facebook
...

net.ubos.underbars.mysql!maindbname=gmimfxladhkoqswy

The first name listed in diet4j!module (here: net.ubos.underbars.mysql) is the main module to activate, while the remainder of the names listed in the same property are additional modules to activate.

In UBOS Linux terms, that makes net.ubos.underbars.mysql the App, and the other modules Accessories. And indeed, this entire .env file is being generated during Deployment of the UBOS Personal Data Mesh on the user’s device, from the information entered in ubos-admin createsite or the provided Site JSON file.

The other property shown in the fragment above is the name of the main MySQL database to be used by this instance of the UBOS Personal Data Mesh. This name is random, and changes, as it is automatically generated by UBOS Linux during Deployment.

What’s the right Site JSON file to use with the UBOS Personal Data Mesh?

There is no one “right” Site JSON file, as you can configure as few or as many Accessories (Models, Viewlets etc) as you like; and depending on what you want to debug, for example, you may very well switch between different configurations.

Here is a link to the Site JSON we created for Developer tutorials for UBOS Mesh.

To deploy the UBOS Personal Data Mesh in this configuration, download this file as site.json and then deploy it as a template like this:

sudo ubos-admin deploy --file site.json --template --verbose

or boot the Docker container for the tutorial as described; this very Site JSON file will be deployed automatically during boot.