Remote Installation
If you prefer this centralized configuration, we provide two main artifacts:
- MWS (Mastro Web Service): the server application which is distributed as a Java
warfile. We suggest to deploy MWS on a Tomcat 9 server installation. - Monolith (Web Application): the front end javascript application (zip file). We suggest to serve it by any Apache HTTP Server
MASTRO_HOME
The environment variable MASTRO_HOME will tell the system which directory in your file system it should use to store all its files (configuration files, ontology and mapping files, etc.).
Configure the system so that Tomcat can see the MASTRO_HOME variable and read/write in that directory in order to manage all the files. Usually you can do this simply adding the definition of the variable in the tomcat.conf in the Tomcat folder such as:
MASTRO_HOME="/var/lib/mastro"
Monolith License
To use Monolith, you need to load the license files in the Mastro Home. Therefore, copy the license.info and license.key files into the MASTRO_HOME/license/ folder, and you’re all set.
Deploy MWS
Just put the war file in the webapps folder of Tomcat. Now restart the Tomcat service in order to get the war file unpacked and deployed: a new context with the name mws-X.Y.Z will be available to the Tomcat users.
Configuration the logging framework
MWS logging layer is based on Logback: in order to configure the log messages to feet your needs, you have to place the logback.xml file into the folder
$CATALINA_HOME/webapps/mws-X.Y.Z/WEB-INF/classes
An example of a basic Logback configuration file follows:
<?xml version="1.0" encoding="UTF-8"?>
<configuration scan="true" scanPeriod="30 seconds">
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
<encoder>
<pattern>
%d{HH:mm:ss} %-5level %logger{36} - %msg [%thread] %n
</pattern>
</encoder>
</appender>
<logger name="com.mwsx.engine.MwsxSessionManager" level="debug"
additivity="false">
<appender-ref ref="STDOUT" />
</logger>
<root level="error">
<appender-ref ref="STDOUT" />
</root>
</configuration>
With this configuration in place MWS will only produce log messages about the creation and maintenance of connection sessions, and such messages will most likely added to the Tomcat catalina.out file, based on the logging configuration of Tomcat itself.
Installing JDBC Drivers
MWS uses JDBC connections to interact with specific DBMSs. To install the JDBC Driver for your DBMS just put the jar files in the lib directory of Tomcat.
Log into the application with administrator rights, access the JDBC Drivers tab of the Settings page and add the driver (class name and, optionally, URL template).
For example, to add the MySQL JDBC Driver, you can insert the following parameters:
- Class name:
com.mysql.cj.jdbc.Driver- URL template:
jdbc:mysql://localhost/
Currently Monolith has specific support (SQL dialects, connectors, ecc.) for all main commercial and open source DBMSs, including:
- Oracle
- SQLServer
- MySQL
- MariaDB
- Cloudera Impala
- PostgreSQL
- Denodo
- DB2
- Derby
- SQLLite
- Impala
For DBMSs not on the list, Monolith provides standard SQL support. Since we are always looking to add more specific SQL dialects, let us know if you have a specific need.
Deploy Monolith
Just copy the extracted files in the folder served by Apache HTTP Server. Then open the browser on the URL configured in your network infrastructure.
Authentication
You can set up a configuration file in order to use a JWT authentication mechanism. All you need to do is create a file named mastro.jwt in the MASTRO_HOME/config folder. The file should look like this:
{
"jwt.claims.valid_audience" : "<audience>",
"jwt.authorities" : "<authorities>",
"jwt.jwks_CA" : "<jwks_CA>",
"jwt.claims.valid-issuer" : "<valid-issuer>"
}
After this configuration mastro will only need to check wheter the sub parameter of the JWT token will match with an existing mastro user.
In order to use mastro web services with JWT monolith need a configuration file. Just edit the config.js file like this:
localStorage.setItem('mastroUrl', '<mastro web services url>/rest/mwsx')
window.jwtConfig = {
"authority": "<jwt authority>",
"client_id": "<jwt client id>",
"redirect_uri": "<url which serves monolith>",
}
For more options, see https://authts.github.io/oidc-client-ts/interfaces/UserManagerSettings.html
When monolith find this configurations, it skips the login page and uses the login procedure issued by the authority.
Example of configurations with Keycloak
Here we will illustrate an example of configuration with Keycloak in order to use JWT authentication with Monolith and Mastro running in development (http://localhost:5173/ and http://localhost:8989).
Run the keycloak server:
docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:21.11 start-dev
In the keycloak admin console, create a new client named ClientMonolith and set the following parameters:
- Valid redirect URIs:
http://localhost:5173/* - Web origins:
http://localhost:5173 - Authentication flow: Standard flow
- Client scopes: ClientMonolith-dedicated -> Add mapper by configuration: (this mapper will be used to override the username with the sub claim of the JWT token which by default is the user id in Keycloak):
- Name: username to sub override
- Property: username
- Token Claim Name: sub
Monolith configuration file config.js should look like this:
window.jwtConfig = {
"authority": "http://localhost:8080/realms/master/",
"client_id": "ClientMonolith",
"redirect_uri": "http://localhost:5173/",
// "checkSessionIntervalInSeconds": 20
}
localStorage.setItem('mastroUrl', 'http://localhost:8989/mws/rest/mwsx')
Mastro configuration file mastro.jwt should look like this:
{
"jwt.claims.valid_audience" : "master-realm",
"jwt.authorities" : "",
"jwt.jwks_CA" : "",
"jwt.claims.valid-issuer" : "http://localhost:8080/realms/master",
"jwt.checker.class.name" : "com.mwsx.configuration.jwt.JWTChecker"
}
When you will open the Monolith application, it will redirect you to the Keycloak login page. After you log in the keycloak form, you will be redirected back to the Monolith application and you will be logged in automatically.
CORS
You can set up a custom CORS configuration if you want to address this security issue. By defalut the server will respond to all requests with Access-Control-Allow-Origin: *. In order to change this config create a file named mastro.cors in the MASTRO_HOME/config folder. The file should look like this:
{
"Access-Control-Allow-Origin" : "http://localhost:3000"
}
Previous Next