Setup¶
This guide describes how to: download, configure, compile and install the last version of Sentilo in your own runtime environment. Moreover, it details which are the infraestructure elements necessary for running Sentilo and how should be their default configuration settings. It’s assumed you have the skils to configure and install the necessary sofware base(Operating System, Maven,JDK, Mongo DB, Redis, etc).
The main topics are:
- Prerequisites: describes the software elements that have to be installed before download the code.
- Download and build: explains the steps to obtain the Sentilo code, to adapt it and how to build the platform artifacts.
- Platform infraestructure: describes the mandatory infraestructure components for running Sentilo and its default configuration settings.
- Deploy the artifacts: describes the necessary steps to deploy all the Sentilo modules
Prerequisites¶
Sentilo uses Maven as a mechanism for building and managing the dependencies of the platform. In order to build Sentilo, it is necessary to ensure the next set of prerequisites:
- JDK 1.8.x +
- Git (optional)
- Maven 3 +
- Ensure that the the Java SDK and Maven executables are accessible using your PATH environment variable.
Download and build code¶
The Sentilo code must be downloaded from Github. Once downloaded, you can build it using a script named buildSentilo.sh which constructs the Sentilo artifacts “out-of-the-box”.
Download the source code from Github¶
The source code of the project can be obtained from git, cloning the remote project in a local directory named sentilo:
git clone https://github.com/sentilo/sentilo.git sentilo
An alternative method is to download a ZIP file from github repository and decompress it in a folder named sentilo:
https://github.com/sentilo/sentilo/archive/master.zip
In both cases, we will finally have a new directory named sentilo with the source code.
Compiling and build artifacts¶
Without changing the default configuration¶
If you want to build Sentilo out-of-the-box (i.e. build all artifacts that define the Sentilo platform without changing any of the default settings that are defined), we distribute a script named ./scripts/buildSentilo.sh which can be used to build Sentilo from the command line.
This script compiles the code and build the artifacts from scratch, but it doesn’t deploy them in the excution environments. This process must be done manually by different reasons, for example:
- The deployment environment could be distributed in different servers. In example, Tomcat server and Pub/Subscribe server.
- it’s not required to install all the components, like the relational database agent.
Changing default settings¶
If you want modify the code before to build it, you should import it into an Eclipse workspace with maven plug-in installed. Below we explain how to do it by using the M2E plugin.
- Open the Eclipse workspace to import the code:
- Go to File> Import> Existing Maven Projects
- Select ./sentilo as the root directory
- Select all projects and import
Warning: be sure that JDK 1.8, or later, is correctly configured in your Eclipse environment.
After modifying the code, to compile and build the artifacts, our recommendation is to use the abovementioned* buildSentilo* script.
Platform infrastructure¶
Before describing how to install all the Sentilo components, we’re going to explain how to configure each element of the infrastructure.
Sentilo uses the following infrastructure elements (they are grouped into two categories):
- Mandatory
- Redis 4.0.11
- MongoDB 4.0.1
- Tomcat 8.5.32 +
- Optional
- MySQL 5.5.x (Sentilo has been tested on MySQL 5.5.34 but you could use your favourite RDBMS) It is only necessary if you want to install the relational agent
- Elasticsearch 5+ It is only necessary if you want to install the activity-monitor agent.
- openTSDB 2.2.0 + It is only necessary if you want to install the historian agent
You must ensure that you have all these elements installed properly (you can find information on how to install them in each provider site).
Below we explain the default settings for each Sentilo module.
Default settings¶
Sentilo configuration uses the Spring and Maven profiles to allow its customization depending on the runtime environment. By default, the platform comes with a predefined profile named dev, which considers that each of these infrastructure elements are installed on the same machine and listening in the following ports:
- Redis: 6379
- MongoDB: 27017
- Tomcat: 8080
- MySQL: 3306
- Elasticsearch: 9200
- openTSDB: 4242
All these settings can be found in the subdirectory /src/main/resources/properties of each platform’s module.
Redis settings¶
Sentilo default settings consider Redis will be listening on port 6379, host 127.0.0.1, and with the parameter requirepass enabled and with value sentilo.
If you change this behaviour, you need to modify the following properties:
jedis.pool.host=127.0.0.1
jedis.pool.port=6379
jedis.pool.password=sentilo
which are configured in the following files:
sentilo-platform/sentilo-platform-service/src/main/resources/properties/jedis-config.properties
sentilo-agent-alert/src/main/resources/properties/jedis-config.properties
sentilo-agent-relational/src/main/resources/properties/jedis-config.properties
sentilo-agent-location-updater/src/main/resources/properties/jedis-config.properties
MongoDB settings¶
Sentilo default settings consider MongoDB will be listening on 127.0.0.1:27017, and requires an existing database named sentilo, created before starting the platform, with authentication enabled and with login credentials preconfigured as sentilo/sentilo (username~:sentilo, password~:sentilo).
If you change this behaviour, you need to modify following properties:
catalog.mongodb.host=127.0.0.1
catalog.mongodb.port=27017
catalog.mongodb.user=sentilo
catalog.mongodb.password=sentilo
configured in the following files:
sentilo-agent-alert/src/main/resources/properties/catalog-config.properties
sentilo-catalog-web/src/main/resources/properties/catalog-config.properties
Data load¶
Moreover, you need to load on sentilo database the basic set of data needed to run the platform. The data include, among other things:
- An user admin: user for log in into the catalog webapp as administrator.
- An user sadmin: user for log in into the catalog webapp with role super-admin.
- A default sentilo tenant: used to configure the default viewer parameters (center, zoom, … ) from the catalog web app.
- An entity sentilo-catalog: internal app used by the platform to synchronize information between its components.
- An user platform_user: internal user used by the platform to synchronize information between its components.
To do this, you must load the data defined in the file:
./scripts/mongodb/init_data.js
For example, in your MongoDB machine, you should execute the following command from the directory where the file is located:
mongo -u sentilo -p sentilo sentilo init_data.js
Remember:
Please keep in mind that data defined in the previous file contains default passwords and tokens (which are recommended for run Sentilo in a test environment). In order to avoid compromissing your platform, we recommend to change them before installing Sentilo in a production environment.
After change their values in the init_data.js and load them on MongoDB, and before compiling and building Sentilo, you will have to modify the following properties:
rest.client.identity.key=c956c302086a042dd0426b4e62652273e05a6ce74d0b77f8b5602e0811025066
catalog.rest.credentials=platform_user:sentilo
configured in the following files:
sentilo-agent-alert/src/main/resources/properties/platform-client-config.properties
sentilo-catalog-web/src/main/resources/properties/catalog-config.properties
sentilo-platform/sentilo-platform-service/src/main/resources/properties/integration.properties
Test data load¶
In order to validate the correct installation of the platform, we could load a set of test data. These data includes, among other things: sensor types, component types, apps and providers.
These data is defined in the file:
./scripts/mongodb/init_test_data.js
and, as pointed aout above, you should run the following command to load it:
mongo -u sentilo -p sentilo sentilo init_test_data.js
MySQL settings¶
Remember:
This software is mandatory only if you want to export the published events to a relational database using the specific agent. Otherwise, you can skip this step. Please, check this out for more info.
Sentilo default settings consider MySQL server will be listening on 127.0.0.1:3306, and requires an existing database named sentilo, created before starting the platform, with authentication enabled and accessible using credentials sentilo_user/sentilo_pwd (username~:sentilo_user, password~:sentilo_pwd).
If you change this behaviour, you need to modify the following properties:
sentiloDs.jdbc.driverClassName=com.mysql.jdbc.Driver
sentiloDs.url=jdbc:mysql://127.0.0.1:3306/sentilo
sentiloDs.username=sentilo_user
sentiloDs.password=sentilo_pwd
configured in the file:
sentilo-agent-relational/src/main/resources/properties/relational-config.properties
Creating the tables¶
Once we have MySQL configured, and the database sentilo created, the next step is to create the database tables required to persist historical platform data.
At the following directory of your Sentilo installation:
sentilo-agent-relational/src/main/resources/bd
you’ll find the script to create these tables.
Tomcat settings¶
Sentilo default settings consider Tomcat will be listening on 127.0.0.1:8080.
If you change this behaviour, you need to modify the following property:
catalog.rest.endpoint=http://127.0.0.1:8080/sentilo-catalog-web/
configured in the following files:
sentilo-platform/sentilo-platform-service/src/main/resources/properties/integration.properties
sentilo-agent-location-updater/src/main/resources/properties/integration.properties
Your Tomcat should also be started with the user timezone environment variable set as UTC. To set Timezone in Tomcat, the startup script (e.g. catalina.sh or setup.sh) must be modified to include the following code:
-Duser.timezone=UTC
Elastisearch settings¶
Remember:
It is only necessary if you want to index into Elasticsearch all the published events using the specific agent. Otherwise, you can skip this step. Please, check this out for more info.
Sentilo default settings consider Elasticsearch server will be listening on localhost:9200. If you change this behaviour, you need to modify the following property:
elasticsearch.url=http://localhost:9200
configured in the following file:
sentilo-agent-activity-monitor/src/main/resources/properties/monitor-config.properties
openTSDB settings¶
Remember:
It is only necessary if you want to store into openTSDB all the published events using the specific agent. Otherwise, you can skip this step. Please, check this out for more info.
Sentilo default settings consider openTSDB server will be listening on 127.0.0.1:4242. If you change this behaviour, you need to modify the following property:
opentsdb.url=http://127.0.0.1:4242
configured in the following file:
sentilo-agent-historian/src/main/resources/properties/historian-config.properties
Subscription/publication platform settings¶
Sentilo default settings consider subscription/publication server (a.k.a. PubSub server) will be listening on 127.0.0.1:8081
If you change this behaviour, you need to modify the following properties:
port=8081
rest.client.host=http://127.0.0.1:8081
configured in the following files:
sentilo-platform/sentilo-platform-server/src/main/resources/properties/config.properties
sentilo-catalog-web/src/main/resources/properties/catalog-config.properties
Configuring logs¶
Sentilo uses slf4j and logback as trace frameworks. The configuration can be found in logback.xml file, located in the subdirectory src/main/resources of sentilo-common module of the platform.
By default, all platform logs are stored in the directory /var/log/sentilo
Platform installation¶
Once you have downloaded the code and you have modify, compile and built it, the next step is to deploy Sentilo artifacts. The platform has five artifacts:
- Web Application Catalog (is mandatory)
- Server publication and subscription (is mandatory)
- Internal agents (are optional):
- alarms agent
- relational database agent
- location updater agent
Installing the Web App Catalog¶
After build Sentilo, to install the Web App, you just need to deploy the WAR artifact in your Tomcat server, i.e., copy the WAR artifact into the webapps subdirectory of your Tomcat server.
You will find the WAR artifact at the following subdirectory:
./sentilo-catalog-web/target/sentilo-catalog-web.war
Installing subscription/publication server¶
After build Sentilo, to install the PubSub server, you need to follow the following steps:
- Into the directory ./sentilo-platform/sentilo-platform-server/target/appassembler you’ll find two subdirectories named repo and bin:
- repo directory contains all libraries needed to run the process
- bin directory contains the script (sentilo-server) needed to initialize the process (there are two scripts, one for Linux systems and one for Windows)
- Copy these two directories in the root directory where you want to install this component (for example: /opt/sentilo-server).
- Once copied, for starting the process you just need to run the script:
$sentilo-server/bin/sentilo-server
Installing agents¶
As have been mentioned previously, all agents are optional and you are free to choose which of them will be deployed, depending on your specific needs. Agents are internal modules oriented to expand the platform functionality without having to alter its core. You will find more information about them in the Integrations section of our documentation.
We have currently seven core agents:
- Alarms agent is responsible for processing each internal alert defined in the catalog and publish a notification (a.k.a. alarm) when any of the configured integrity rules are not met. You need this agent if you want to make use of the internal alerts functionality provided by Sentilo.
- Relational agent is responsible for store all information received from the PubSub server into a set of relational databases. You need this agent if you want to persist data published in Sentilo in a relational database too.
- Location updater agent is responsible for updating automatically the component location according to the location of the published observations.
- Historian agent is responsible for store all information received from the PubSub server into a time series database. You need this agent if you want to persist data published in Sentilo in openTSDB too.
- Activity monitor agent is responsible for index all information received from the PubSub server into a search engine server. You need this agent if you want to store data published in Sentilo into Elasticsearch too.
- Kafka agent Publishes events to Kafka.
- Federation agent Synchronizes two independent Sentilo instances, publishing selected observations from a set of providers to another Sentilo.
Remember: As mentioned before, Sentilo always store all published events into Redis.
All the agents are installed in a similar manner to the PubSub server, as described below.
Installing alarms agent¶
After build Sentilo, to install the alarms agent, you need to follow the following steps:
- Into the directory ./sentilo-agent-alert/target/appassembler you’ll find two subdirectories named repo and bin:
- repo directory contains all libraries needed to run the process
- bin directory contains the script (sentilo-agent-alert-server) needed to initialize the process (there are two scripts, one for Linux systems and one for Windows)
- Copy these two directories in the root directory where you want to install this component (for example: /opt/sentilo-agent-alert).
- Once copied, for starting the process you just need to run the following script:
$sentilo-agent-alert/bin/sentilo-agent-alert-server
Installing relational agent¶
As mentioned before, this agent exports all the received data, orders and alarms to a database named sentilo and located in the MySQL server.
These configuration settings are defined in the files:
./sentilo-agent-relational/src/main/resources/properties/subscription.properties
./sentilo-agent-relational/src/main/resources/properties/relational-client-config.properties
To modify this behavior, just follow the instructions given in the properties files.
Additionally, with the purpose of optimizing the persistence process, insert process is done in batch mode and uses a retries parameter aimed to minimize any error. By default, the batch size is fixed to 10 records and the retries parameter is defined to 1.
This behaviour can be changed editing the file:
./sentilo-agent-relational/src/main/resources/properties/relational-client-config.properties
and updating the following lines:
# Properties to configure the batch update process
relational.batch.size=10
relational.batch.workers.size=3
relational.batch.max.retries=1
After building Sentilo, to install the relational agent, you only need to follow the following steps:
- Into the directory ./sentilo-agent-relational/target/appassembler you’ll find two subdirectories named repo and bin:
- repo directory contains all libraries needed to run the process
- bin directory contains the script (sentilo-agent-relational-server) needed to initialize the process (there are two scripts, one for Linux systems and one for Windows)
- Copy these two directories in the root directory where you want to install this component (for example: /opt/sentilo-agent-relational).
- Once copied, for starting the process you just need to run the script:
$sentilo-agent-relational/bin/sentilo-agent-relational-server
Installing location updater agent¶
After building Sentilo, to install the location updater agent, you need to follow the following steps:
- Into the directory ./sentilo-agent-location-updater/target/appassembler you’ll find two subdirectories named repo and bin:
- repo directory contains all libraries needed to run the process
- bin directory contains the script (sentilo-agent-location-updater-server) needed to initialize the process (there are two scripts, one for Linux systems and one for Windows)
- Copy these two directories in the root directory where you want to install this component (for example: /opt/sentilo-agent-location-updater).
- Once copied, for starting the process you just need to run the script:
$sentilo-agent-location-updater/bin/sentilo-agent-location-updater-server
Installing historian agent¶
As mentioned before, this agent exports all the received events to a openTSDB server.
This agent works in a similar way to the relational agent: insert process is done in batch mode and uses a retries parameter aimed to minimize any error. By default, the batch size is fixed to 10 records and the retries parameter is defined to 1.
This behaviour can be changed editing the file:
./sentilo-agent-historian/src/main/resources/properties/historian-config.properties
and updating the following lines:
# Properties to configure the batch update process
batch.size=10
batch.workers.size=3
batch.max.retries=1
After building Sentilo, to install the historian agent, you only need to follow the following steps:
- Into the directory ./sentilo-agent-historian/target/appassembler you’ll find two subdirectories named repo and bin:
- repo directory contains all libraries needed to run the process
- bin directory contains the script (sentilo-agent-historian-server) needed to initialize the process (there are two scripts, one for Linux systems and one for Windows)
- Copy these two directories in the root directory where you want to install this component (for example: /opt/sentilo-agent-historian).
- Once copied, for starting the process you just need to run the script:
$sentilo-agent-historian/bin/sentilo-agent-historian-server
Installing activity-monitor agent¶
As mentioned before, this agent exports all the received events to elasticsearch server.
This agent works in a similar way to the relational agent: insert process is done in batch mode and uses a retries parameter aimed to minimize any error. By default, the batch size is fixed to 10 records and the retries parameter is defined to 1.
This behaviour can be changed editing the file:
./sentilo-agent-historian/src/main/resources/properties/monitor-config.properties
and updating the following lines:
# Properties to configure the batch update process
batch.size=10
batch.workers.size=3
batch.max.retries=1
After building Sentilo, to install the activity-monitor agent, you only need to follow the following steps:
- Into the directory ./sentilo-agent-activity-monitor/target/appassembler you’ll find two subdirectories named repo and bin:
- repo directory contains all libraries needed to run the process
- bin directory contains the script (sentilo-agent-activity-monitor-server) needed to initialize the process (there are two scripts, one for Linux systems and one for Windows)
- Copy these two directories in the root directory where you want to install this component (for example: /opt/sentilo-agent-activity-monitor).
- Once copied, for starting the process you just need to run the script:
$sentilo-agent-activity-monitor/bin/sentilo-agent-activity-monitor-server
Enable multi-tenant instance¶
In order to enable multi-tenant feature you need to ensure that your Sentilo version is at least 1.5.0. Otherwise you will have to upgrade your Sentilo instance.
Once the above requirement is fulfilled, you only need to do the following steps:
Modify your Tomcat startup script¶
You should modify your Tomcat startup script (e.g %TOMCAT_HOME%/bin/catalina.sh or %TOMCAT_HOME%/bin/setenv.sh) to add a new JVM property:
-Dsentilo.multitenant=true
Once you have added the JVM property, you must restart your Tomcat server.
Edit the Catalog web.xml file¶
The next step is to edit the Catalog file web.xml located at:
sentilo-catalog-web/src/main/webapp/WEB-INF/web.xml
You will find some lines that are commented into this file which are needed to enable the multi-tenant feature. Therefore you should uncomment them:
<!--
<filter>
<filter-name>UrlRewriteFilter</filter-name>
<filter-class>org.tuckey.web.filters.urlrewrite.UrlRewriteFilter</filter-class>
<init-param>
<param-name>logLevel</param-name>
<param-value>slf4j</param-value>
</init-param>
</filter>
<filter>
<filter-name>tenantInterceptorFilter</filter-name>
<filter-class>org.sentilo.web.catalog.web.TenantInterceptorFilter</filter-class>
</filter>
-->
<!--
<filter-mapping>
<filter-name>tenantInterceptorFilter</filter-name>
<url-pattern>/*</url-pattern>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>
<filter-mapping>
<filter-name>UrlRewriteFilter</filter-name>
<url-pattern>/*</url-pattern>
<dispatcher>REQUEST</dispatcher>
<dispatcher>FORWARD</dispatcher>
</filter-mapping>
-->
Once you have uncomment the above lines, you should recompile the Catalog webapp module and redeploy it into your Tomcat server.
You will find more information about this feature in the Multi-Tenant section of our documentation.
Enable anonymous access to REST API¶
By default, anonymous access to REST API is disabled which means that all requests to REST API must be identified with the identity_key header.
From version 1.5, we provide a new feature that allows anonymous access to REST API but only for read authorized data of your Sentilo instance (here authorized means that you should configure your Catalog to define which data could be accessed anonymously from REST requests).
In order to enable anonymous access you should modify the following properties:
# Properties to configure the anonymous access to Sentilo
enableAnonymousAccess=false
anonymousAppClientId=
configured in the following file:
sentilo-platform/sentilo-platform-server/src/main/resources/properties/config.properties
This configuration has not mystery: if anonymous access is enabled (enableAnonymousAccess=true) then all anonymous requests to REST API are internally considered as is they have been performed by the application client identified by the anonymousAppClientId property value (this application client should exists into your Sentilo Catalog), and therefore these requests will have the same data restrictions as the requests performed by this client application.
What next?¶
Check the Quick Start Page or Platform Testing page.