===== 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
-------------------------------------------------------------------
52 | Active |  80 | 2.3.1   | Gson
53 | Active |  80 | 18.0.0  | Guava: Google Core Libraries for Java
54 | Active |  80 | 2.0.6   | Messaging Service API
55 | Active |  90 | 2.0.7   | MQTT Messaging Service
56 | Active |  80 | 2.1.2   | Middleware API
57 | Active |  90 | 2.1.2   | Middleware Service implementation
58 | Active |  80 | 2.5     | Commons Lang
69 | 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.