Merge 99b1246 into 4791356

README.md

@@ -1,35 +1,81 @@
-# perseo
+# Perseo Context-Aware CEP
 
 [![FIWARE Processing](https://nexus.lab.fiware.org/static/badges/chapters/processing.svg)](https://www.fiware.org/developers/catalogue/)
-[![License: APGL](https://img.shields.io/github/license/telefonicaid/perseo-fe.svg)](https://opensource.org/licenses/AGPL-3.0)
-<br/>
+[![License: AGPLv3](https://img.shields.io/github/license/telefonicaid/perseo-fe.svg)](./LICENSE)
+[![Docker Status](https://img.shields.io/docker/pulls/fiware/perseo.svg)](https://hub.docker.com/r/fiware/perseo/)
+[![Support badge](https://img.shields.io/badge/tag-fiware--perseo-orange.svg?logo=stackoverflow)](https://stackoverflow.com/questions/tagged/fiware-perseo)
+<br> [![Documentation badge](https://img.shields.io/readthedocs/perseo.svg)](https://perseo.readthedocs.io/en/latest/)
 [![CI](https://github.com/telefonicaid/perseo-fe/workflows/CI/badge.svg)](https://github.com/telefonicaid/perseo-fe/actions?query=workflow%3ACI)
 [![Coverage Status](https://coveralls.io/repos/github/telefonicaid/perseo-fe/badge.svg?branch=master)](https://coveralls.io/github/telefonicaid/perseo-fe?branch=master)
 ![Status](https://nexus.lab.fiware.org/static/badges/statuses/perseo.svg)
 
-CEP implementation for IoT platform
+## Overview
 
-## Index
+Perseo is a Complex Event Processing (CEP) software designed to be fully _NGSI-v2_-compliant. It uses NGSI-v2 as the
+communication protocol for events, and thus, Perseo is able to seamless and jointly work with _context brokers_. The
+context broker tested with Perseo and officially supported is
+[Orion Context Broker](https://github.com/telefonicaid/fiware-orion).
 
--   [Architecture](documentation/architecture.md)
--   [Logs & Alarms](documentation/logs.md)
--   O&M
+This project is part of [FIWARE](https://www.fiware.org). You can find more FIWARE components in the
+[FIWARE catalogue](https://catalogue.fiware.org).
 
-    -   [Deployment](documentation/deployment.md)
-    -   [Configuration](documentation/configuration.md)
-    -   [Administration](documentation/admin.md)
-    -   [Metrics API](documentation/metrics_api.md)
+| :books: [Documentation](https://perseo.readthedocs.io/en/latest) | :whale: [Docker Hub](https://hub.docker.com/r/fiware/perseo/) | :dart: [Roadmap](documentation/roadmap.md) |
+| ---------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------ |
 
--   [API](documentation/api.md)
-    -   [Plain rules](documentation/plain_rules.md)
-    -   [Errors](documentation/errors.md)
--   [Data model](documentation/models.md)
--   [Available actions for PEP](documentation/pep_actions.md)
--   [Documentation for developers of perseo](documentation/development.md)
 
-| :dart: [Roadmap](documentation/roadmap.md) |
-| ------------------------------------------ |
+## Content
 
+-   [Background](#background)
+-   [Installation](#installation)
+-   [Usage](#usage)
+-   [API](#api)
+-   [Testing](#testing)
+-   [More Information](#more-information)
+-   [License](#license)
+
+## Background
+
+Perseo is an [Esper-based](http://www.espertech.com/esper/) Complex Event Processing (CEP) software designed to be fully
+_NGSI-v2_-compliant.
+
+It follows a straightforward idea: listening to events coming from context information to identify patterns described by
+rules, in order to immediately react upon them by triggering actions.
+
+![Perseo Components](docs/images/PerseoComponents.png)
+
+By leveraging on the
+[notifications mechanism](http://fiware-orion.readthedocs.io/en/latest/user/walkthrough_apiv2/index.html#subscriptions),
+clients instruct Orion CB to notify Perseo of the changes in the entities they care about (`Event API`). Details of this
+process are explained in the [Orion Subscription part of the User Manual](user/index.md#orion-subscription). Then, rules
+to the CORE Rule Engine can be easily managed using the publicly available
+[WireCloud](https://github.com/Wirecloud/wirecloud)) operational dashboard, or making use of any of the REST clients
+able to programmaticly use the Perseo's `Rule API`. These rules will identify patterns that will trigger actions with
+Orion to create or update entities, or with other different components or external systems, such as Web (HTTP), Email
+(SMTP) or SMS (SMPP) servers.
+
+## Installation
+
+The instructions to install Perseo can be found in the [Deployment Guide](docs/admin/deployment.md)
+
+## Usage
+
+Information about how to use Perseo can be found in the [User & Programmers Manual](docs/user/index.md)
+
+## API
+
+APIs and examples of their usage can be found [here](docs/API/api.md)
+
+## Testing
+
+For performing a basic end-to-end test, you can follow the detailed instructions
+[here](docs/developer/development.md#Testing).
+
+## More Information
+
+-   Refer to the
+    [Esper Reference Documentation](http://esper.espertech.com/release-8.4.0/reference-esper/html/index.html) for info
+    on how to use EPL as a rule language.
+-   [Full Perseo documentation](docs/README.md)
 
 ## License
 

docker-compose.yml

@@ -0,0 +1,68 @@
+#
+# Copyright 2016 Telefonica Investigación y Desarrollo, S.A.U
+#
+# This file is part of perseo-fe
+#
+# perseo-fe is free software: you can redistribute it and/or modify it under the terms of the GNU Affero
+# General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+# perseo-fe is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the
+# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License
+# for more details.
+#
+# You should have received a copy of the GNU Affero General Public License along with perseo-fe. If not, see
+# http://www.gnu.org/licenses/.
+#
+# For those usages not covered by the GNU Affero General Public License please contact with iot_support at tid dot es
+#
+
+version: '3.4'
+services:
+    perseo-mongo:
+        image: mongo:4.2
+        volumes:
+            - ./mongodata:/data/db
+        networks:
+            - perseo
+        deploy:
+            replicas: 1
+            restart_policy:
+                condition: on-failure
+    perseo-core:
+        image: fiware/perseo-core
+        environment:
+            - PERSEO_FE_URL=http://perseo-fe:9090
+            - MAX_AGE=6000
+        networks:
+            - perseo
+        depends_on:
+            - perseo-mongo
+        deploy:
+            replicas: 1
+            restart_policy:
+                condition: on-failure
+    perseo-fe:
+        image: fiware/perseo
+        networks:
+            perseo:
+            main:
+        ports:
+            - 9090:9090
+        depends_on:
+            - perseo-core
+        environment:
+            - PERSEO_MONGO_ENDPOINT=perseo-mongo
+            - PERSEO_CORE_URL=http://perseo-core:8080
+            - PERSEO_LOG_LEVEL=debug
+            - PERSEO_ORION_URL=http://orion:1026/
+            - PERSEO_SMTP_HOST=www.hostname.com
+            - PERSEO_SMTP_PORT=25
+            - PERSEO_SMTP_SECURE=false
+        deploy:
+            replicas: 1
+            restart_policy:
+                condition: on-failure
+
+networks:
+    perseo:
+    main:

documentation/api.md → docs/API/api.md

@@ -1,6 +1,6 @@
-<a name="API"></a>
+## API
 
-We are working on apiary descriptions for the API methods, that will come soon ...
+**FIXME:** A draft OpenAPI document for the API is available [here](perseo-api.yml), but it is not finished yet.
 
 A description of "plain"" rules can be found at [plain rules](plain_rules.md).
 
@@ -10,8 +10,6 @@ old format eventually. So, basically, the DCA's documentation is the reference.
 Notices/notifications follow the format defined in Orion (Context Broker) for "notify" actions.
 [Context subscriptions](https://fiware-orion.readthedocs.io/en/master/user/walkthrough_apiv2/index.html#subscriptions)
 
-## API
-
 All HTTP request must have `application/json` as MIME type. Responses are `application/json` also. Generally, the JSON
 returned as response includes a `error` field with a string describing an error or `null` if everything worked fine.
 

documentation/metrics_api.md → docs/API/metrics_api.md

@@ -1,4 +1,4 @@
-#<a name="top"></a>Metrics API
+## <a name="top"></a>Metrics API
 
 -   [Introduction](#introduction)
 -   [Operations](#operations)
@@ -7,13 +7,13 @@
     -   [Get and reset](#get-and-reset)
 -   [Metrics](#metrics)
 
-## Introduction
+### Introduction
 
 Perseo implements a REST-based API that can be used to get relevant operational metrics.
 
 [Top](#top)
 
-## Operations
+### Operations
 
 #### Get metrics
 
@@ -36,7 +36,7 @@ object with information for the aggregated information for all services.
     "service2": <service 2 info>,
     ...
     "serviceN": <service N info>
-  }
+  },
   "sum": <aggregated info for all services>
 }
 ```
@@ -53,7 +53,7 @@ given services.
     "subservice2": <subservice 2 info>,
     ...
     "subserviceN": <subservice N info>
-  }
+  },
   "sum": <aggregated info for all subservice in the given service>
 }
 ```
@@ -81,7 +81,7 @@ Some additional remarks:
 
 [Top](#top)
 
-### Reset metrics
+#### Reset metrics
 
 ```text
 DELETE /admin/metrics
@@ -91,7 +91,7 @@ This operation resets all metrics, as if Perseo would had just been started.
 
 [Top](#top)
 
-### Get and reset
+#### Get and reset
 
 ```text
 GET /admin/metrics?reset=true
@@ -102,7 +102,7 @@ resets metrics.
 
 [Top](#top)
 
-## Metrics
+### Metrics
 
 The following metrics are common with other IoT platform componentes (e.g. Orion Contex Broker):
 

documentation/pep_actions.md → docs/API/pep_actions.md

@@ -1,5 +1,3 @@
-<a name="actions"></a>
-
 ## Available actions
 
 The available actions are: