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.