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:

  1. 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)
  1. Copy these two directories in the root directory where you want to install this component (for example: /opt/sentilo-server).
  2. 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:

  1. 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)
  1. Copy these two directories in the root directory where you want to install this component (for example: /opt/sentilo-agent-alert).
  2. 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:

  1. 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)
  1. Copy these two directories in the root directory where you want to install this component (for example: /opt/sentilo-agent-relational).
  2. 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:

  1. 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)
  1. Copy these two directories in the root directory where you want to install this component (for example: /opt/sentilo-agent-location-updater).
  2. 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:

  1. 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)
  1. Copy these two directories in the root directory where you want to install this component (for example: /opt/sentilo-agent-historian).
  2. 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:

  1. 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)
  1. Copy these two directories in the root directory where you want to install this component (for example: /opt/sentilo-agent-activity-monitor).
  2. 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.