[2/3] incubator-unomi git commit: We are now versioning the documentation, making it easier to publish a history of documentation.

[shuber]

http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/27301696/src/site/markdown/versions/1.1/concepts.md
--
diff --git a/src/site/markdown/versions/1.1/concepts.md 
b/src/site/markdown/versions/1.1/concepts.md
new file mode 100644
index 000..6947c5b
--- /dev/null
+++ b/src/site/markdown/versions/1.1/concepts.md
@@ -0,0 +1,209 @@
+
+
+# Concepts
+
+Apache Unomi gathers information about users actions, information that is 
processed and stored by Unomi services. The collected information can then be 
used to personalize content, derive insights on user behavior, categorize the 
user profiles into segments along user-definable dimensions or acted upon by 
algorithms.
+
+## Items and types
+Unomi structures the information it collects using the concept of `Item` which 
provides the base information (an identifier and a type) the context server 
needs to process and store the data. Items are persisted according to their 
type (structure) and identifier (identity). This base structure can be 
extended, if needed, using properties in the form of key-value pairs.
+
+These properties are further defined by the `Item`’s type definition which 
explicits the `Item`’s structure and semantics. By defining new types, users 
specify which properties (including the type of values they accept) are 
available to items of that specific type.
+
+Unomi defines default value types: `date`, `email`, `integer` and `string`, 
all pretty self-explanatory. While you can think of these value types as 
"primitive" types, it is possible to extend Unomi by providing additional value 
types.
+
+
+Additionally, most items are also associated to a scope, which is a concept 
that Unomi uses to group together related items. A given scope is represented 
in Unomi by a simple string identifier and usually represents an application or 
set of applications from which Unomi gathers data, depending on the desired 
analysis granularity. In the context of web sites, a scope could, for example, 
represent a site or family of related sites being analyzed. Scopes allow 
clients accessing the context server to filter data to only see relevant data.
+
+*Base `Item` structure:*
+
+```json
+{
+  "itemType": ,
+  "scope": ,
+  "itemId": ,
+  "properties": 
+}
+```
+
+Some types can be dynamically defined at runtime by calling to the REST API 
while other extensions are done via Unomi plugins. Part of extending Unomi, 
therefore, is a matter of defining new types and specifying which kind of Unomi 
entity (e.g. profiles) they can be affected to. For example, the following JSON 
document can be passed to Unomi to declare a new property type identified (and 
named) `tweetNb`, tagged with the `social` tag, targeting profiles and using 
the `integer` value type.
+
+*Example JSON type definition:*
+
+```json
+{
+"itemId": "tweetNb",
+"itemType": "propertyType",
+"metadata": {
+"id": "tweetNb",
+"name": "tweetNb"
+},
+"tags": ["social"],
+"target": "profiles",
+"type": "integer"
+}
+```
+
+
+>Unomi defines a built-in scope (called `systemscope`) that clients can use to 
share data across scopes.
+
+## Events
+Users' actions are conveyed from clients to the context server using events. 
Of course, the required information depends on what is collected and users' 
interactions with the observed systems but events minimally provide a type, a 
scope and source and target items. Additionally, events are timestamped. 
Conceptually, an event can be seen as a sentence, the event's type being the 
verb, the source the subject and the target the object.
+
+
+*Event structure:*
+
+```json
+{
+"eventType": ,
+"scope": ,
+"source": ,
+"target": ,
+"properties": 
+}
+```
+
+Source and target can be any Unomi item but are not limited to them. In 
particular, as long as they can be described using properties and Unomi’s 
type mechanism and can be processed either natively or via extension plugins, 
source and target can represent just about anything. Events can also be 
triggered as part of Unomi’s internal processes for example when a rule is 
triggered.
+
+Events are sent to Unomi from client applications using the JSON format and a 
typical page view event from a web site could look something like the following:
+
+*Example page view event:*
+
+```json
+{
+"eventType": "view",
+"scope": "ACMESPACE",
+"source": {
+"itemType": "site",
+"scope": "ACMESPACE",
+"itemId": "c4761bbf-d85d-432b-8a94-37e866410375"
+},
+"target": {
+"itemType": "page",
+"scope": "ACMESPACE",
+"itemId": "b6acc7b3-6b9d-4a9f-af98-54800ec13a71",
+"properties": {
+"pageInfo": {
+"pageID": "b6acc7b3-6b9d-4a9f-af98-54800ec13a71",
+"pageName": "Home",
+"pagePath": "/sites/ACMESPACE/home",
+"destinationURL": 

[3/3] incubator-unomi git commit: We are now versioning the documentation, making it easier to publish a history of documentation.

[shuber]

We are now versioning the documentation, making it easier to publish a history 
of documentation.

Signed-off-by: Serge Huber 


Project: http://git-wip-us.apache.org/repos/asf/incubator-unomi/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-unomi/commit/27301696
Tree: http://git-wip-us.apache.org/repos/asf/incubator-unomi/tree/27301696
Diff: http://git-wip-us.apache.org/repos/asf/incubator-unomi/diff/27301696

Branch: refs/heads/master
Commit: 27301696c393a6a9a5a9d5cb95ed08e18094848a
Parents: 06030be
Author: Serge Huber 
Authored: Fri Feb 17 17:45:26 2017 +0100
Committer: Serge Huber 
Committed: Fri Feb 17 17:45:26 2017 +0100

--
 src/site/markdown/building-and-deploying.md | 217 --
 src/site/markdown/clustering.md |  66 ---
 src/site/markdown/concepts.md   | 209 -
 src/site/markdown/configuration.md  | 305 -
 src/site/markdown/getting-started.md| 423 ---
 .../versions/1.1/building-and-deploying.md  | 189 +
 src/site/markdown/versions/1.1/clustering.md|  83 
 src/site/markdown/versions/1.1/concepts.md  | 209 +
 src/site/markdown/versions/1.1/configuration.md | 273 
 .../markdown/versions/1.1/getting-started.md| 423 +++
 .../versions/master/building-and-deploying.md   | 217 ++
 src/site/markdown/versions/master/clustering.md |  66 +++
 src/site/markdown/versions/master/concepts.md   | 209 +
 .../markdown/versions/master/configuration.md   | 305 +
 .../markdown/versions/master/getting-started.md | 423 +++
 src/site/site.xml   |  19 +-
 16 files changed, 2411 insertions(+), 1225 deletions(-)
--


http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/27301696/src/site/markdown/building-and-deploying.md
--
diff --git a/src/site/markdown/building-and-deploying.md 
b/src/site/markdown/building-and-deploying.md
deleted file mode 100644
index f4fbfb8..000
--- a/src/site/markdown/building-and-deploying.md
+++ /dev/null
@@ -1,217 +0,0 @@
-
-Building
-
-
-Initial Setup
--
-
-1) Install J2SE 8.0 SDK (or later), which can be downloaded from
-   http://www.oracle.com/technetwork/java/javase/downloads/index.html
-
-2) Make sure that your JAVA_HOME environment variable is set to the newly 
installed
-   JDK location, and that your PATH includes %JAVA_HOME%\bin (windows) or
-   $JAVA_HOME$/bin (unix).
-
-3) Install Maven 3.0.3 (or later), which can be downloaded from
-   http://maven.apache.org/download.html. Make sure that your PATH includes
-   the MVN_HOME/bin directory.
-
-
-Building
-
-
-1) Change to the top level directory of Apache Unomi source distribution.
-2) Run
-
- $> mvn clean install
-
-   This will compile Apache Unomi and run all of the tests in the
-   Apache Unomi source distribution. Alternatively, you can run
-
- $> mvn -P \!integration-tests,\!performance-tests clean install
-
-   This will compile Apache Unomi without running the tests and takes less
-   time to build.
-
-3) The distributions will be available under "package/target" directory.
-
-Installing an ElasticSearch server
---
-
-Starting with version 1.2, Apache Unomi no longer embeds an ElasticSearch 
server as this is no longer supported by 
-the developers of ElasticSearch. Therefore you will need to install a 
standalone ElasticSearch using the following steps:
-
-1. Download an ElasticSearch 5.x version (5.1.1 or more recent, but not 6.x) 
from the following site:
-
-https://www.elastic.co/downloads/elasticsearch
-
-2. Uncompress the downloaded package into a directory and launch the server 
using
-
-bin/elasticsearch (Mac, Linux)
-bin\elasticsearch.bat (Windows)
-
-3. Check that the ElasticSearch is up and running by accessing the following 
URL : 
-
-http://localhost:9200
-
-Deploying the generated binary package
---
-
-The "package" sub-project generates a pre-configured Apache Karaf installation 
that is the simplest way to get started.
-Simply uncompress the package/target/unomi-VERSION.tar.gz (for Linux or Mac OS 
X) or
- package/target/unomi-VERSION.zip (for Windows) archive into the directory of 
your choice.
- 
-You can then start the server simply by using the command on UNIX/Linux/MacOS 
X : 
-
-./bin/karaf start
-
-or on Windows shell : 
-
-bin\karaf.bat start
-
-
-Deploying into an existing Karaf server

-
-This is only needed if you didn't use the generated package. Also, this is the 
preferred way to install a 

[1/3] incubator-unomi git commit: We are now versioning the documentation, making it easier to publish a history of documentation.

[shuber]

Repository: incubator-unomi
Updated Branches:
  refs/heads/master 06030beff -> 27301696c


http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/27301696/src/site/markdown/versions/master/configuration.md
--
diff --git a/src/site/markdown/versions/master/configuration.md 
b/src/site/markdown/versions/master/configuration.md
new file mode 100644
index 000..5880732
--- /dev/null
+++ b/src/site/markdown/versions/master/configuration.md
@@ -0,0 +1,305 @@
+
+
+Configuration
+=
+
+Changing the default configuration
+--
+
+If you want to change the default configuration, you can perform any 
modification you want in the $MY_KARAF_HOME/etc directory.
+
+The context server configuration is kept in the 
$MY_KARAF_HOME/etc/org.apache.unomi.cluster.cfg . It defines the
+addresses and port where it can be found :
+
+contextserver.address=localhost
+contextserver.port=8181
+contextserver.secureAddress=localhost
+contextserver.securePort=9443
+
+If you need to specify an Elasticsearch cluster name, or a host and port that 
are different than the default, 
+it is recommended to do this BEFORE you start the server for the first time, 
or you will loose all the data 
+you have stored previously.
+
+To change these settings, you will need to modify a file called 
+
+$MY_KARAF_HOME/etc/org.apache.unomi.persistence.elasticsearch.cfg
+
+with the following contents:
+
+cluster.name=contextElasticSearch
+# The elasticSearchAddresses may be a comma seperated list of host names 
and ports such as
+# hostA:9300,hostB:9300
+# Note: the port number must be repeated for each host.
+elasticSearchAddresses=localhost:9300
+index.name=context
+
+Secured events configuration
+---
+
+If you need to secure some events, that will be sent only by a trusted third 
party server, you can update the file :
+
+$MY_KARAF_HOME/etc/org.apache.unomi.thirdparty.cfg
+
+Ususally, login events, which operate on profiles and do merge on protected 
properties, must be secured. For each
+trusted third party server, you need to add these 3 lines :
+
+thirdparty.provider1.key=secret-key
+thirdparty.provider1.ipAddresses=127.0.0.1,::1
+thirdparty.provider1.allowedEvents=login,download
+
+The events set in allowedEvents will be secured and will only be accepted if 
the call comes from the specified IP
+address, and if the secret-key is passed in the X-Unomi-Peer header.
+
+Installing the MaxMind GeoIPLite2 IP lookup database
+
+
+The Context Server requires an IP database in order to resolve IP addresses to 
user location.
+The GeoLite2 database can be downloaded from MaxMind here :
+http://dev.maxmind.com/geoip/geoip2/geolite2/
+
+Simply download the GeoLite2-City.mmdb file into the "etc" directory.
+
+Installing Geonames database
+
+
+Context server includes a geocoding service based on the geonames database ( 
http://www.geonames.org/ ). It can be
+used to create conditions on countries or cities.
+
+In order to use it, you need to install the Geonames database into . Get the 
"allCountries.zip" database from here :
+http://download.geonames.org/export/dump/
+
+Download it and put it in the "etc" directory, without unzipping it.
+Edit $MY_KARAF_HOME/etc/org.apache.unomi.geonames.cfg and set 
request.geonamesDatabase.forceImport to true, import should start right away.
+Otherwise, import should start at the next startup. Import runs in background, 
but can take about 15 minutes.
+At the end, you should have about 4 million entries in the geonames index.
+ 
+REST API Security
+-
+
+The Context Server REST API is protected using JAAS authentication and using 
Basic or Digest HTTP auth.
+By default, the login/password for the REST API full administrative access is 
"karaf/karaf".
+
+The generated package is also configured with a default SSL certificate. You 
can change it by following these steps :
+
+1. Replace the existing keystore in $MY_KARAF_HOME/etc/keystore by your own 
certificate :
+ 
+http://wiki.eclipse.org/Jetty/Howto/Configure_SSL
+
+2. Update the keystore and certificate password in 
$MY_KARAF_HOME/etc/custom.properties file :
+ 
+```
+org.osgi.service.http.secure.enabled = true
+org.ops4j.pax.web.ssl.keystore=${karaf.etc}/keystore
+org.ops4j.pax.web.ssl.password=changeme
+org.ops4j.pax.web.ssl.keypassword=changeme
+org.osgi.service.http.port.secure=9443
+```
+
+You should now have SSL setup on Karaf with your certificate, and you can test 
it by trying to access it on port 9443.
+
+3. Changing the default Karaf password can be done by modifying the 
etc/users.properties file
+
+4. You will also need to change the user/password information in the 
org.apache.unomi.cluster.cfg file : 
+
+```
+cluster.group=default
+

[jira] [Created] (UNOMI-81) Add entry point to Definitions service to allow tag creation

[Damien GAILLARD (JIRA)]

Damien GAILLARD created UNOMI-81:


 Summary: Add entry point to Definitions service to allow tag 
creation
 Key: UNOMI-81
 URL: https://issues.apache.org/jira/browse/UNOMI-81
 Project: Apache Unomi
  Issue Type: Improvement
Affects Versions: 1.2.0-incubating
Reporter: Damien GAILLARD
Assignee: Damien GAILLARD
 Fix For: 1.2.0-incubating






--
This message was sent by Atlassian JIRA
(v6.3.15#6346)