Differences

This shows you the differences between two versions of the page.

--- sensorweaver:admin-guide [2014-12-22 11:38] – created luigi.fortunati
+++ sensorweaver:admin-guide [2017-12-04 14:40] (current) – davide
@@ Line 1: / Line 1: @@
 ===== Administrator Guide =====
+This guide shows how to setup an OSGi execution environment with the Middleware platform services.
+The guide assume that:
+  * You have a java 8 JRE installed on your system
+  * You have basic knowledge on the administration of the [[http://karaf.apache.org/index.html|Karaf]] OSGi container
+==== MQTT Broker ====
+The communication platforms relies on MQTT at the lowest communication layer.
+On linux/windows machines you can easily install the Mosquitto MQTT broker by downloading it on the [[http://mosquitto.org/|official website]].
+Ubuntu repositories alredy host a Mosquitto package, install it using apt with
+<code>
+sudo apt-get install mosquitto
+</code>
+Without any further configuration you should already have an instance of mosquitto running on your machine, with open access on port 1883.
+==== Karaf ====
+We strongly recommend Apache Karaf as the OSGi container of choice. You have two choices:
+  * <del>Download a preconfigure Apache Karaf bundle</del>
+  * Download Apache Karaf and use [[http://ala.isti.cnr.it:8081/nexus/index.html#nexus-search;gav~~sensorweaver-features~~xml~features|sensorweaver karaf features]]
+=== SensorWeaver Karaf Bundle ===
+<del>The preconfigured SensorWeaver karaf bundle can be downloaded from this {{:sensorweaver:sensorweaver-karaf-bundle.tar.gz|link}}.
+That is based on Karaf 3.0.2 and already includes a default configuration that will launch the execution environment (Middleware included) with minimal effort required.
+You can install your bundles in the container and test it using Karaf [[http://karaf.apache.org/manual/latest/developers-guide/debugging.html|debug and logging tools]].</del>
+=== SensorWeaver features ===
+Alternatively you can download an Apache Karaf Distribution from the [[http://karaf.apache.org/index/community/download.html|Karaf download page]] and add the feature file manually.
+Please refer to Karaf [[http://karaf.apache.org/manual/latest/users-guide/provisioning.html|documentation]] to setup the feature repositores.
+To use sensorweaver features you first have to setup the maven repo in file 'org.ops4j.pax.url.mvn.cfg' under karaf etc folder.
+The last lines of the file should look like this:
+<file properties org.ops4j.pax.url.mvn.cfg>
+....
+http://repository.springsource.com/maven/bundles/external@id=spring-ebr-repository@snapshots@noreleases, \
+http://ala.isti.cnr.it:8081/nexus/content/repositories/wnlab-releases@id=wnlab-releases, \
+http://ala.isti.cnr.it:8081/nexus/content/repositories/wnlab-snapshots@id=wnlab-snapshots@snapshots
+</file>
+Including the snapshot repository is not mandatory.
+To install the whole set of middleware bundles, start karaf and execute the following karaf console commands:
+<code console>
+karaf@root()> feature:repo-add mvn:it.cnr.isti.sensorweaver/sensorweaver-features/2.1.4/xml/features
+Adding feature url mvn:it.cnr.isti.sensorweaver/sensorweaver-features/2.1.4/xml/features
+karaf@root()> feature:install middleware
+karaf@root()> list
+START LEVEL 100 , List Threshold: 50
+ID | State  | Lvl | Version | Name
+-------------------------------------------------------------------
+| Active |  80 | 2.3.1   | Gson
+| Active |  80 | 18.0.0  | Guava: Google Core Libraries for Java
+| Active |  80 | 2.0.6   | Messaging Service API
+| Active |  90 | 2.0.7   | MQTT Messaging Service
+| Active |  80 | 2.1.2   | Middleware API
+| Active |  90 | 2.1.2   | Middleware Service implementation
+| Active |  80 | 2.5     | Commons Lang
+| Active |  80 | 1.0.2   | Paho MQTT Client
+</code>
+The feature will install with default bundle configuration. At this point you can stop karaf and manually configure the bundles by modifying property files under the karaf 'etc' folder.
+==== Bundles configuration ====
+Middleware needs two components to be configured in order to run:
+  * Messaging configuration
+  * Middleware configuration
+Keep in mind that, since the Middleware components are stateful services, the configuration cannot be updated at runtime without disrupting clients, hence a bundle restart is required each time the configuration is changed.
+Middleware components will just ignore dynamic changes to their configuration at runtime.
+Messaging configuration includes the target MQTT broker and security options.
+Default messaging system configuration assumes that you have a MQTT broker listening on localhost on port 1883, without security enabled.
+You can modify messaging system configuration by creating a configuration file in the ''etc'' folder of Apache Karaf.
+Here is the default configuration:
+<file properties it.cnr.isti.sensorweaver.messaging.mqtt.cfg>
+host=localhost
+port=1883
+truststorePassword=
+keystorePassword=
+truststorePath=
+keystorePath=
+username=
+password=
+mode=anonymous
+</file>
+Messaging layer can follow one of these broker authentication mechanisms (mode field):
+  * //anonymous//: broker must be set to allow anonmyous clients
+  * //password//: by setting the mode to password the messaging layer will connect to the broker using the //username// and //password// provided in the available fields. Refer to the broker documentation to set the authentication credentials.
+  * //certificate//: certificate based authentication. Refer to [[https://mosquitto.org/man/mosquitto-tls-7.html|this]] guide for the creation of the keys and certificates (comprising the CA certificate).
+Middleware configuration includes a scope name assigned to the middleware instance. A scope identify an area of visibility of data on the Middleware.
+Each middleware instance is assigned a nodeId at startup. The nodeId can be set via configuration. If an ID is not provided, the hostname is used.
+Here is the default configuration:
+<file properties it.cnr.isti.sensorweaver.middleware.cfg>
+scope=default
+nodeId=
+</file>
+The scope defines a domain under which messages are published on the broker and is the first level of each topic used for message publication.
+The nodeId, if not provided, defaults to the client hostname. It can be set manually by configuration.