From 9632678c1b5eb7fe595a6600e40b5e80715b86c4 Mon Sep 17 00:00:00 2001 From: Felipe Ripoll Date: Mon, 20 Aug 2018 18:35:56 -0600 Subject: [PATCH] [#71] Adding Getting Started guide --- README.md | 3 +- config/prod.exs | 4 +- doc/.build | 4 +- doc/404.html | 4 +- doc/POAAgent.Application.html | 4 +- doc/POAAgent.Entity.NameConvention.html | 4 +- ...AAgent.Format.POAProtocol.Data.Format.html | 4 +- doc/POAAgent.Plugins.Collector.html | 6 +- ...nt.Plugins.Collectors.Eth.Information.html | 4 +- ...nt.Plugins.Collectors.Eth.LatestBlock.html | 4 +- ...AAgent.Plugins.Collectors.Eth.Pending.html | 4 +- ...POAAgent.Plugins.Collectors.Eth.Stats.html | 4 +- doc/POAAgent.Plugins.Transfer.html | 6 +- ...nt.Plugins.Transfers.WebSocket.Primus.html | 4 +- doc/POAAgent.html | 222 ++++++++++++++++++ doc/api-reference.html | 11 +- doc/dist/sidebar_items-303975f305.js | 1 + doc/dist/sidebar_items-d9b3f5cff8.js | 1 - doc/index.html | 2 +- doc/initial_architecture.html | 4 +- doc/search.html | 4 +- doc/starting_guide.html | 216 +++++++++++++++++ lib/poa_agent.ex | 117 +++++++++ mix.exs | 6 +- pages/starting_guide.md | 172 ++++++++++++++ 25 files changed, 777 insertions(+), 38 deletions(-) create mode 100644 doc/POAAgent.html create mode 100644 doc/dist/sidebar_items-303975f305.js delete mode 100644 doc/dist/sidebar_items-d9b3f5cff8.js create mode 100644 doc/starting_guide.html create mode 100644 lib/poa_agent.ex create mode 100644 pages/starting_guide.md diff --git a/README.md b/README.md index 903dd46..c6cb476 100644 --- a/README.md +++ b/README.md @@ -3,11 +3,10 @@ [![Coverage Status](https://coveralls.io/repos/github/poanetwork/poa-netstats-agent/badge.svg?branch=master)](https://coveralls.io/github/poanetwork/poa-netstats-agent?branch=master) [![codecov](https://codecov.io/gh/poanetwork/poa-netstats-agent/branch/master/graph/badge.svg)](https://codecov.io/gh/poanetwork/poa-netstats-agent) -**TODO: Add description** - ## Documentation - [Initial Architecture](pages/initial_architecture.md) +- [Getting Started](pages/starting_guide.md) - You can find the online documentation [here](https://rawgit.com/poanetwork/poa-netstats-agent/master/doc/index.html) Or you can build the documenation locally running diff --git a/config/prod.exs b/config/prod.exs index 294dc28..a0c259e 100644 --- a/config/prod.exs +++ b/config/prod.exs @@ -26,8 +26,8 @@ config :poa_agent, identifier: "elixirNodeJSIntegration", # Authentication parameters - user: "971Iwekd", - password: "9BOZIf1uGHi2FIB", + user: "BK3eiZcT", + password: "MPr1n9B-ipvpYbj", token_url: "https://localhost:4003/session" ] } diff --git a/doc/.build b/doc/.build index b5fa2cf..b053b38 100644 --- a/doc/.build +++ b/doc/.build @@ -4,11 +4,13 @@ fonts/icomoon.eot fonts/icomoon.svg fonts/icomoon.ttf fonts/icomoon.woff -dist/sidebar_items-d9b3f5cff8.js +dist/sidebar_items-303975f305.js api-reference.html initial_architecture.html +starting_guide.html search.html 404.html +POAAgent.html POAAgent.Application.html POAAgent.Entity.NameConvention.html POAAgent.Format.POAProtocol.Data.Format.html diff --git a/doc/404.html b/doc/404.html index 643b78c..876620e 100644 --- a/doc/404.html +++ b/doc/404.html @@ -8,7 +8,7 @@ 404 – poa_agent v0.1.0 - + @@ -29,7 +29,7 @@
- +

poa_agent diff --git a/doc/POAAgent.Application.html b/doc/POAAgent.Application.html index 2c1fa7c..ef627de 100644 --- a/doc/POAAgent.Application.html +++ b/doc/POAAgent.Application.html @@ -8,7 +8,7 @@ POAAgent.Application – poa_agent v0.1.0 - + @@ -29,7 +29,7 @@
- +

poa_agent diff --git a/doc/POAAgent.Entity.NameConvention.html b/doc/POAAgent.Entity.NameConvention.html index f0b3bb2..0b3dccc 100644 --- a/doc/POAAgent.Entity.NameConvention.html +++ b/doc/POAAgent.Entity.NameConvention.html @@ -8,7 +8,7 @@ POAAgent.Entity.NameConvention – poa_agent v0.1.0 - + @@ -29,7 +29,7 @@
- +

poa_agent diff --git a/doc/POAAgent.Format.POAProtocol.Data.Format.html b/doc/POAAgent.Format.POAProtocol.Data.Format.html index ff15bc6..ee4f4b1 100644 --- a/doc/POAAgent.Format.POAProtocol.Data.Format.html +++ b/doc/POAAgent.Format.POAProtocol.Data.Format.html @@ -8,7 +8,7 @@ POAAgent.Format.POAProtocol.Data.Format – poa_agent v0.1.0 - + @@ -29,7 +29,7 @@
- +

poa_agent diff --git a/doc/POAAgent.Plugins.Collector.html b/doc/POAAgent.Plugins.Collector.html index bdbe4a6..63ccc7c 100644 --- a/doc/POAAgent.Plugins.Collector.html +++ b/doc/POAAgent.Plugins.Collector.html @@ -8,7 +8,7 @@ POAAgent.Plugins.Collector – poa_agent v0.1.0 - + @@ -29,7 +29,7 @@
- +

poa_agent @@ -84,7 +84,7 @@

Defines a Collector Plugin.

A Collector plugin will run in an independent process and will run the collect/1 function in a given frequency.

-

POAAgent app reads the Collectors configuration from the config.exs file when bootstrap and will create a +

POAAgent app reads the Collectors configuration from the config.exs file when bootstrap and will create a process per each one of them. That configuration is referenced by :collectors key.

config :poa_agent,
    :collectors,
diff --git a/doc/POAAgent.Plugins.Collectors.Eth.Information.html b/doc/POAAgent.Plugins.Collectors.Eth.Information.html
index 875f232..b0adf50 100644
--- a/doc/POAAgent.Plugins.Collectors.Eth.Information.html
+++ b/doc/POAAgent.Plugins.Collectors.Eth.Information.html
@@ -8,7 +8,7 @@
     POAAgent.Plugins.Collectors.Eth.Information – poa_agent v0.1.0
     
     
-    
+    
     
     
     
@@ -29,7 +29,7 @@
 

 
   
-  
+  
     

       

         poa_agent
diff --git a/doc/POAAgent.Plugins.Collectors.Eth.LatestBlock.html b/doc/POAAgent.Plugins.Collectors.Eth.LatestBlock.html
index 20c4d87..795baf1 100644
--- a/doc/POAAgent.Plugins.Collectors.Eth.LatestBlock.html
+++ b/doc/POAAgent.Plugins.Collectors.Eth.LatestBlock.html
@@ -8,7 +8,7 @@
     POAAgent.Plugins.Collectors.Eth.LatestBlock – poa_agent v0.1.0
     
     
-    
+    
     
     
     
@@ -29,7 +29,7 @@
 

 
   
-  
+  
     

       

         poa_agent
diff --git a/doc/POAAgent.Plugins.Collectors.Eth.Pending.html b/doc/POAAgent.Plugins.Collectors.Eth.Pending.html
index bd1a3f1..b0bdc4b 100644
--- a/doc/POAAgent.Plugins.Collectors.Eth.Pending.html
+++ b/doc/POAAgent.Plugins.Collectors.Eth.Pending.html
@@ -8,7 +8,7 @@
     POAAgent.Plugins.Collectors.Eth.Pending – poa_agent v0.1.0
     
     
-    
+    
     
     
     
@@ -29,7 +29,7 @@
 

 
   
-  
+  
     

       

         poa_agent
diff --git a/doc/POAAgent.Plugins.Collectors.Eth.Stats.html b/doc/POAAgent.Plugins.Collectors.Eth.Stats.html
index fa47a03..03dc1f8 100644
--- a/doc/POAAgent.Plugins.Collectors.Eth.Stats.html
+++ b/doc/POAAgent.Plugins.Collectors.Eth.Stats.html
@@ -8,7 +8,7 @@
     POAAgent.Plugins.Collectors.Eth.Stats – poa_agent v0.1.0
     
     
-    
+    
     
     
     
@@ -29,7 +29,7 @@
 

 
   
-  
+  
     

       

         poa_agent
diff --git a/doc/POAAgent.Plugins.Transfer.html b/doc/POAAgent.Plugins.Transfer.html
index 94e7ee3..b90947f 100644
--- a/doc/POAAgent.Plugins.Transfer.html
+++ b/doc/POAAgent.Plugins.Transfer.html
@@ -8,7 +8,7 @@
     POAAgent.Plugins.Transfer – poa_agent v0.1.0
     
     
-    
+    
     
     
     
@@ -29,7 +29,7 @@
 

 
   
-  
+  
     

       

         poa_agent
@@ -84,7 +84,7 @@
           
Defines a Transfer Plugin.

 
A Transfer plugin receives data from Collectors. It uses the Collector’s label in order to
 differenciate from multiple Collectors.

-
POAAgent app reads the Transfers configuration from the config.exs file when bootstrap and will create a
+
POAAgent app reads the Transfers configuration from the config.exs file when bootstrap and will create a
 process per each one of them. That configuration is referenced by :transfers key.

 
config :poa_agent,
    :transfers,
diff --git a/doc/POAAgent.Plugins.Transfers.WebSocket.Primus.html b/doc/POAAgent.Plugins.Transfers.WebSocket.Primus.html
index 849faa9..2bb0ee5 100644
--- a/doc/POAAgent.Plugins.Transfers.WebSocket.Primus.html
+++ b/doc/POAAgent.Plugins.Transfers.WebSocket.Primus.html
@@ -8,7 +8,7 @@
     POAAgent.Plugins.Transfers.WebSocket.Primus – poa_agent v0.1.0
     
     
-    
+    
     
     
     
@@ -29,7 +29,7 @@
 

 
   
-  
+  
     

       

         poa_agent
diff --git a/doc/POAAgent.html b/doc/POAAgent.html
new file mode 100644
index 0000000..fdedeb0
--- /dev/null
+++ b/doc/POAAgent.html
@@ -0,0 +1,222 @@
+    
+
+  
+    
+    
+    
+    
+    POAAgent – poa_agent v0.1.0
+    
+    
+    
+    
+    
+    
+    
+  
+  
+    
+
+    

+
+
+

+
+  
+  
+    

+      

+        poa_agent
+      

+      

+        v0.1.0
+      

+    

+    
+  
+
+  

+    
+    
+  

+
+  
+  

+  
+

+
+

+  

+    

+
+
+      

+        poa_agent v0.1.0
+        POAAgent
+        
+          
+            
+            View Source
+          
+        
+      

+
+      
+        

+          
POAAgent

+
Coverage Status
+codecov

+

+  
+  Documentation
+

+
+
+
Or you can build the documenation locally running

+
mix deps.get
+mix docs

+
That command will create a doc/ folder with the actual Documentation.

+

+  
+  Run
+

+
+
POAAgent is an Elixir application, in order to run it first we need to fetch the dependencies and compile it.

+
mix deps.get
+mix deps.compile
+mix compile

+
To run the Elixir application while under development it may be convenient to use:
+env MIX_ENV=dev mix run --no-halt with an appropiate configuration in /config/dev.exs.

+

+  
+  Run Tests
+

+
+
In order to run the tests we have to run the command

+
mix test

+
POAAgent comes also with a code analysis tool Credo and a types checker tool Dialyxir. In order to run them we have to run

+
mix credo
+mix dialyzer

+

+  
+  Building & Deploying an Executable
+

+
+
To build an executable you’ll need Elixir 1.6 (and Erlang/OTP 20).

+
    
+
  1. Once you have a copy of this repository configure the agent for production in the file config/prod.exs.
+
    2. 
+
  2. An real configuration example can be found in the default config/prod.exs.
+
    3. 
+
  3. Do a mix deps.get to fetch, among other dependencies, the tooling for building server executables.
+
    4. 
+
  4. A env MIX_ENV=prod mix release --name=poa_agent --env=prod will assemble an executable.
+
    5. 
+

+
A resulting artifact resides at _build/prod/rel/poa_agent/releases/0.1.0/poa_agent.tar.gz which you can move to a remote host.
+Use tar xfz then bin/poa_agent start (bin/poa_agent stop will stop the server cleanly).

+
If you want to run it on the local host then the procedure is as simple as: _build/prod/rel/poa_agent/bin/poa_agent.

+
Note: executables must be built on the platform (OS and architecture) they are destined for under the project’s current configuration.
+Other options are possible (see https://hexdocs.pm/distillery/getting-started.html).

+

+  
+  Configuration
+

+
+
Executables are built with a configuration as described above.
+However the transfers and collectors are configurable at run-time through a JSON configuration.
+To configure this supply a path to a JSON file with the config_overlay key/value.
+The following is an extract from config/test.exs:

+
config :poa_agent,
+    config_overlay: "config/config_overlay.json"

+
A corresponding example is provided in config/config_overlay.json:

+
{
+    "POAAgent":{
+        "collectors":[
+            {
+                "id": "eth_information",
+                "url": "http://localhost:8546",
+                "name": "NewNodeName",
+                "contact": "mynewemail@gmail.com"
+            }
+        ],
+        "transfers":[
+            {
+                "id": "rest_transfer",
+                "address": "http://localhost:4003",
+                "identifier": "NewIdentifier",
+                "secret": "newsecret"
+            }
+        ]
+    }
+}
+

+
The file can reside anywhere on the machine that the Elixir executable has access to.
+The key/value pairs in the JSON configuration will replace the defaults specified in the Elixir configuration (i.e. config/{dev,test,prod}.exs).

+

+  
+  Coverage
+

+
+
To get an HTML coverage report on your own machine try env MIX_ENV=test mix coveralls.html then open cover/excoveralls.html.
+You can get a simple print-out with env MIX_ENV=test mix coveralls.

+
+        

+      
+
+      
+
+      
+
+      
+
+      
+          
+    

+  

+

+

+  
+  
+  
+  
+  
+  
+
+
diff --git a/doc/api-reference.html b/doc/api-reference.html
index 4de00e2..a642da1 100644
--- a/doc/api-reference.html
+++ b/doc/api-reference.html
@@ -8,7 +8,7 @@
     API Reference – poa_agent v0.1.0
     
     
-    
+    
     
     
     
@@ -29,7 +29,7 @@
 

 
   
-  
+  
     

       

         poa_agent
@@ -82,6 +82,13 @@
 
     

       

+  
POAAgent

+  
+    
POAAgent

+

+  
+

+

   
POAAgent.Application

   
     
This module implements the Application behaviour

diff --git a/doc/dist/sidebar_items-303975f305.js b/doc/dist/sidebar_items-303975f305.js
new file mode 100644
index 0000000..9db6ad7
--- /dev/null
+++ b/doc/dist/sidebar_items-303975f305.js
@@ -0,0 +1 @@
+sidebarNodes={"extras":[{"id":"api-reference","title":"API Reference","group":"","headers":[{"id":"Modules","anchor":"modules"}]},{"id":"initial_architecture","title":"Initial Architecture","group":"","headers":[{"id":"Network Agent Architecture","anchor":"network-agent-architecture"},{"id":"Network Server Architecture","anchor":"network-server-architecture"}]},{"id":"starting_guide","title":"Getting Started","group":"","headers":[{"id":"Setting up","anchor":"setting-up"},{"id":"Connecting to POA Warehouse","anchor":"connecting-to-poa-warehouse"}]}],"exceptions":[],"modules":[{"id":"POAAgent","title":"POAAgent","group":""},{"id":"POAAgent.Application","title":"POAAgent.Application","group":"","functions":[{"id":"start/2","anchor":"start/2"}]},{"id":"POAAgent.Entity.NameConvention","title":"POAAgent.Entity.NameConvention","group":"","functions":[{"id":"from_elixir_to_node/1","anchor":"from_elixir_to_node/1"}],"types":[{"id":"t/0","anchor":"t:t/0"}]},{"id":"POAAgent.Format.POAProtocol.Data.Format","title":"POAAgent.Format.POAProtocol.Data.Format","group":"","functions":[{"id":"to_data/1","anchor":"to_data/1"}],"types":[{"id":"t/0","anchor":"t:t/0"}]},{"id":"POAAgent.Plugins.Transfers.WebSocket.Primus","title":"POAAgent.Plugins.Transfers.WebSocket.Primus","group":"","functions":[{"id":"data_received/3","anchor":"data_received/3"},{"id":"handle_message/2","anchor":"handle_message/2"},{"id":"init_transfer/1","anchor":"init_transfer/1"},{"id":"terminate/1","anchor":"terminate/1"}]},{"id":"POAAgent.Plugins.Collector","title":"POAAgent.Plugins.Collector","group":"Plugins","callbacks":[{"id":"collect/1","anchor":"c:collect/1"},{"id":"init_collector/1","anchor":"c:init_collector/1"},{"id":"terminate/1","anchor":"c:terminate/1"}]},{"id":"POAAgent.Plugins.Transfer","title":"POAAgent.Plugins.Transfer","group":"Plugins","callbacks":[{"id":"data_received/3","anchor":"c:data_received/3"},{"id":"handle_message/2","anchor":"c:handle_message/2"},{"id":"init_transfer/1","anchor":"c:init_transfer/1"},{"id":"terminate/1","anchor":"c:terminate/1"}]},{"id":"POAAgent.Plugins.Collectors.Eth.Information","title":"POAAgent.Plugins.Collectors.Eth.Information","group":"Ethereum Plugins"},{"id":"POAAgent.Plugins.Collectors.Eth.LatestBlock","title":"POAAgent.Plugins.Collectors.Eth.LatestBlock","group":"Ethereum Plugins"},{"id":"POAAgent.Plugins.Collectors.Eth.Pending","title":"POAAgent.Plugins.Collectors.Eth.Pending","group":"Ethereum Plugins"},{"id":"POAAgent.Plugins.Collectors.Eth.Stats","title":"POAAgent.Plugins.Collectors.Eth.Stats","group":"Ethereum Plugins"}],"tasks":[]}
\ No newline at end of file
diff --git a/doc/dist/sidebar_items-d9b3f5cff8.js b/doc/dist/sidebar_items-d9b3f5cff8.js
deleted file mode 100644
index f3435e2..0000000
--- a/doc/dist/sidebar_items-d9b3f5cff8.js
+++ /dev/null
@@ -1 +0,0 @@
-sidebarNodes={"extras":[{"id":"api-reference","title":"API Reference","group":"","headers":[{"id":"Modules","anchor":"modules"}]},{"id":"initial_architecture","title":"Initial Architecture","group":"","headers":[{"id":"Network Agent Architecture","anchor":"network-agent-architecture"},{"id":"Network Server Architecture","anchor":"network-server-architecture"}]}],"exceptions":[],"modules":[{"id":"POAAgent.Application","title":"POAAgent.Application","group":"","functions":[{"id":"start/2","anchor":"start/2"}]},{"id":"POAAgent.Entity.NameConvention","title":"POAAgent.Entity.NameConvention","group":"","functions":[{"id":"from_elixir_to_node/1","anchor":"from_elixir_to_node/1"}],"types":[{"id":"t/0","anchor":"t:t/0"}]},{"id":"POAAgent.Format.POAProtocol.Data.Format","title":"POAAgent.Format.POAProtocol.Data.Format","group":"","functions":[{"id":"to_data/1","anchor":"to_data/1"}],"types":[{"id":"t/0","anchor":"t:t/0"}]},{"id":"POAAgent.Plugins.Transfers.WebSocket.Primus","title":"POAAgent.Plugins.Transfers.WebSocket.Primus","group":"","functions":[{"id":"data_received/3","anchor":"data_received/3"},{"id":"handle_message/2","anchor":"handle_message/2"},{"id":"init_transfer/1","anchor":"init_transfer/1"},{"id":"terminate/1","anchor":"terminate/1"}]},{"id":"POAAgent.Plugins.Collector","title":"POAAgent.Plugins.Collector","group":"Plugins","callbacks":[{"id":"collect/1","anchor":"c:collect/1"},{"id":"init_collector/1","anchor":"c:init_collector/1"},{"id":"terminate/1","anchor":"c:terminate/1"}]},{"id":"POAAgent.Plugins.Transfer","title":"POAAgent.Plugins.Transfer","group":"Plugins","callbacks":[{"id":"data_received/3","anchor":"c:data_received/3"},{"id":"handle_message/2","anchor":"c:handle_message/2"},{"id":"init_transfer/1","anchor":"c:init_transfer/1"},{"id":"terminate/1","anchor":"c:terminate/1"}]},{"id":"POAAgent.Plugins.Collectors.Eth.Information","title":"POAAgent.Plugins.Collectors.Eth.Information","group":"Ethereum Plugins"},{"id":"POAAgent.Plugins.Collectors.Eth.LatestBlock","title":"POAAgent.Plugins.Collectors.Eth.LatestBlock","group":"Ethereum Plugins"},{"id":"POAAgent.Plugins.Collectors.Eth.Pending","title":"POAAgent.Plugins.Collectors.Eth.Pending","group":"Ethereum Plugins"},{"id":"POAAgent.Plugins.Collectors.Eth.Stats","title":"POAAgent.Plugins.Collectors.Eth.Stats","group":"Ethereum Plugins"}],"tasks":[]}
\ No newline at end of file
diff --git a/doc/index.html b/doc/index.html
index 9a4e51e..21c979a 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -3,7 +3,7 @@
   
     
     poa_agent v0.1.0 – Documentation
-    
+    
     
     
   
diff --git a/doc/initial_architecture.html b/doc/initial_architecture.html
index 9c97e23..7be5b19 100644
--- a/doc/initial_architecture.html
+++ b/doc/initial_architecture.html
@@ -8,7 +8,7 @@
     Initial Architecture – poa_agent v0.1.0
     
     
-    
+    
     
     
     
@@ -29,7 +29,7 @@
 

 
   
-  
+  
     

       

         poa_agent
diff --git a/doc/search.html b/doc/search.html
index df8db57..f2545ed 100644
--- a/doc/search.html
+++ b/doc/search.html
@@ -8,7 +8,7 @@
     Search – poa_agent v0.1.0
     
     
-    
+    
     
     
     
@@ -29,7 +29,7 @@
 

 
   
-  
+  
     

       

         poa_agent
diff --git a/doc/starting_guide.html b/doc/starting_guide.html
new file mode 100644
index 0000000..ba6c160
--- /dev/null
+++ b/doc/starting_guide.html
@@ -0,0 +1,216 @@
+
+
+  
+    
+    
+    
+    
+    Getting Started – poa_agent v0.1.0
+    
+    
+    
+    
+    
+    
+    
+  
+  
+    
+
+

+
+
+

+
+  
+  
+    

+      

+        poa_agent
+      

+      

+        v0.1.0
+      

+    

+    
+  
+
+  

+    
+    
+  

+
+  
+  

+  
+

+
+

+  

+    

+
+
+
Starting Guide

+
With this guide we are going to go thru an example of how to set up the agent and connect with the POA Warehouse.

+
Brief introduction

+
POAAgent is built on top of a Collector’s Plugin Mechanism. You can add, remove and create your own one. We have developed some collectors but you can create your own ones. Check how to implement a collector.

+
The Collectors send data to Transfers. A transfer is an Elixir process which will receive the data. You can implement your own Transfer, check this. We have developed a transfer in order to send data to the POA Warehouse.

+
Every collector can send data to one or many different transfers. The mapping between collectors and Transfers is done in the config file.

+
In our example we are going to add 4 collectors

+
    
+
  • Information Collector: This collector sends Ethereum info to the Transfers periodically.
+
    • 
+
  • Latest Block Collector: This collector “listens” the Ethereum node checking if a new block has been added. Once a new token is detected it will be sent to the mapped Transfers.
+
    • 
+
  • Stats Collector: This collector checks periodically the Ethereum node in order to see if the stats has changed. When changed it will send the data to the transfers.
+
    • 
+
  • Pending Transactions Collector: This collector checks with the Ethereum node if the value of “Pending Transactions” has changed, if that is the case it will send the data to the Transfers.
+
    • 
+

+

+  
+  Setting up
+

+
+
The collectors we want to use need an Ethereum node to monitor so we will need the host:port. In our example my Ethereum node is running in http://localhost:8545

+
In order to configure the Agent we have to fill a config file. In this case we are going to call it prod.exs. We are going to fill it step by step:

+
We have use the Mix.Config module, this is needed in every Elixir Config file.

+
use Mix.Config

+
Next we have to indicate the overlay configuration, you can check how that works here but in our case the config_overlay.json will remain without changes.

+
config :poa_agent,
+    config_overlay: "config/config_overlay.json"

+
Now we need the Ethereumex configuration. Ethereumex is the Elixir library we are using to communicate with the Ethereum node. There we have to put the Ethereum url.

+
config :ethereumex,
+    url: "http://localhost:8545"

+
We also need the configuration for the Collectors, here we have to indicate the ones we are going to use.

+
config :poa_agent, 
+       :collectors,
+       [
+         {:eth_information, POAAgent.Plugins.Collectors.Eth.Information, 60_000, :eth_information, [url: "http://localhost:8545", name: "Elixir-NodeJS-Integration", contact: "myemail@gmail.com"]},
+         {:eth_latest_block, POAAgent.Plugins.Collectors.Eth.LatestBlock, 500, :latest_block, [url: "http://localhost:8545"]},
+         {:eth_stats, POAAgent.Plugins.Collectors.Eth.Stats, 5000, :eth_stats, [url: "http://localhost:8545"]},
+         {:eth_pending, POAAgent.Plugins.Collectors.Eth.Pending, 500, :eth_pending, [url: "http://localhost:8545"]}
+         
+       ]

+
You can check in the docs what each field mean in the configuration but it is quite straightforward.

+
Now we are going to configure the Transfer information. For now we are not going to use transfers (we will check how to use the Warehouse transfer later).

+
config :poa_agent, 
+       :transfers,
+       [
+       ]

+
The last steps is configuring the mapping. Mapping is where we say to which Transfers each Collector is going to send the data. In our case is straightforward since we are not using Transfers

+
config :poa_agent,
+       :mappings,
+       [
+         {:eth_latest_block, []},
+         {:eth_stats, []},
+         {:eth_pending, []},
+         {:eth_information, []}
+       ]

+
with this configuration the agent must be able to start running the command

+
MIX_ENV=prod iex -S mix

+
MIX_ENV=prod sets a Environment variable used by mix to prod. We are using that variable for choosing the config files. That means we are going to use prod.exs as a configuration file.

+
This will start the agent directly in the terminal. If you want to create a release you must read this

+

+  
+  Connecting to POA Warehouse
+

+
+
In order to connect with POA Warehouse we have to use a Transfer which is aligned with the POA’s protocol. We have developed a Transfer called REST which implements the REST version of the POA’s protocol. In order to use it we have to declare it in the Config file.

+
Let’s update the transfers section in the prod.exs file

+
config :poa_agent, 
+       :transfers,
+       [
+         {:rest_transfer, POAAgent.Plugins.Transfers.HTTP.REST, [
+             address: "http://localhost:4002",
+             identifier: "elixirNodeJSIntegration",
+
+             # Authentication parameters
+             user: "",
+             password: "",
+             token_url: ""
+           ]
+         }
+       ]

+
Well, it seems we need some Auth parameters before starting the Agent. We need a valid user with a valid password and we also need a url in order to request JWT tokens

+
First we will create a valid user/password. If you want to join POA’s network you have to ask them for a new user/password. If you have access to the Warehouse you have to call the create user endpoint.

+
Let’s assume we have access to the Warehouse and it is running in https://localhost:4003. We start asking for a user/password with a valid Admin user and Admin Password. The Admin is “admin1” and the password “password12345678”. We can find the documentation about the user endpoint here.

+
curl -i -X POST -H "Authorization: Basic YWRtaW4xOnBhc3N3b3JkMTIzNDU2Nzg=" -H "Content-Type: application/json" https://localhost:4003/user --insecure
+
+HTTP/1.1 200 OK
+server: Cowboy
+date: Tue, 21 Aug 2018 00:18:29 GMT
+content-length: 53
+cache-control: max-age=0, private, must-revalidate
+
+{"user-name":"BK3eiZcT","password":"MPr1n9B-ipvpYbj"}

+
There we have our user name and password. We also know the token url is in https://localhost:4003/session. Now we have to update the config file.

+
config :poa_agent, 
+       :transfers,
+       [
+         {:rest_transfer, POAAgent.Plugins.Transfers.HTTP.REST, [
+             address: "http://localhost:4002",
+             identifier: "elixirNodeJSIntegration",
+
+             # Authentication parameters
+             user: "BK3eiZcT",
+             password: "MPr1n9B-ipvpYbj",
+             token_url: "https://localhost:4003/session"
+           ]
+         }
+       ]

+
We have more configuration to update. Since we have added a Transfer we have to send data to it, so we have to make all the collectors sending data to that rest_transfer

+
config :poa_agent,
+       :mappings,
+       [
+         {:eth_latest_block, [:rest_transfer]},
+         {:eth_stats, [:rest_transfer]},
+         {:eth_pending, [:rest_transfer]},
+         {:eth_information, [:rest_transfer]}
+       ]

+
Now we can stop the agent and start again.

+
MIX_ENV=prod iex -S mix

+
Now you will see in the Agent’s terminal the transfer is requesting a token and sending data to the Warehouse.

+
+      
+    

+  

+

+

+  
+  
+  
+  
+  
+  
+
+
diff --git a/lib/poa_agent.ex b/lib/poa_agent.ex
new file mode 100644
index 0000000..b82e2a6
--- /dev/null
+++ b/lib/poa_agent.ex
@@ -0,0 +1,117 @@
+defmodule POAAgent do
+
+  @moduledoc """
+  # POAAgent
+
+  [![Coverage Status](https://coveralls.io/repos/github/poanetwork/poa-netstats-agent/badge.svg?branch=master)](https://coveralls.io/github/poanetwork/poa-netstats-agent?branch=master)
+  [![codecov](https://codecov.io/gh/poanetwork/poa-netstats-agent/branch/master/graph/badge.svg)](https://codecov.io/gh/poanetwork/poa-netstats-agent)
+
+  ## Documentation
+
+  - [Initial Architecture](pages/initial_architecture.md)
+  - You can find the online documentation [here](https://rawgit.com/poanetwork/poa-netstats-agent/master/doc/index.html)
+  - [Getting Started](starting_guide.html)
+
+  Or you can build the documenation locally running
+
+  ```
+  mix deps.get
+  mix docs
+  ```
+
+  That command will create a `doc/` folder with the actual Documentation.
+
+  ## Run
+
+  POAAgent is an Elixir application, in order to run it first we need to fetch the dependencies and compile it.
+
+  ```
+  mix deps.get
+  mix deps.compile
+  mix compile
+  ```
+
+  To run the Elixir application while under development it may be convenient to use:
+  `env MIX_ENV=dev mix run --no-halt` with an appropiate configuration in `/config/dev.exs`.
+
+  ## Run Tests
+
+  In order to run the tests we have to run the command
+
+  ```
+  mix test
+  ```
+
+  `POAAgent` comes also with a code analysis tool [Credo](https://github.com/rrrene/credo) and a types checker tool [Dialyxir](https://github.com/jeremyjh/dialyxir). In order to run them we have to run
+
+  ```
+  mix credo
+  mix dialyzer
+  ```
+
+  ## Building & Deploying an Executable
+
+  To build an executable you'll need Elixir 1.6 (and Erlang/OTP 20).
+
+  1. Once you have a copy of this repository configure the agent for production in the file `config/prod.exs`.
+  2. An real configuration example can be found in the default `config/prod.exs`.
+  3. Do a `mix deps.get` to fetch, among other dependencies, the tooling for building server executables.
+  4. A `env MIX_ENV=prod mix release --name=poa_agent --env=prod` will assemble an executable.
+
+  A resulting artifact resides at `_build/prod/rel/poa_agent/releases/0.1.0/poa_agent.tar.gz` which you can move to a remote host.
+  Use `tar xfz` then `bin/poa_agent start` (`bin/poa_agent stop` will stop the server cleanly).
+
+  If you want to run it on the local host then the procedure is as simple as: `_build/prod/rel/poa_agent/bin/poa_agent`.
+
+  **Note:** executables must be built on the platform (OS and architecture) they are destined for under the project's current configuration.
+  Other options are possible (see `https://hexdocs.pm/distillery/getting-started.html`).
+
+  ## Configuration
+
+  Executables are built with a configuration as described above.
+  However the transfers and collectors are configurable at run-time through a JSON configuration.
+  To configure this supply a path to a JSON file with the `config_overlay` key/value.
+  The following is an extract from [config/test.exs](config/test.exs):
+
+  ```Elixir
+  config :poa_agent,
+      config_overlay: "config/config_overlay.json"
+  ```
+
+  A corresponding example is provided in `config/config_overlay.json`:
+
+  ```JSON
+  {
+      "POAAgent":{
+          "collectors":[
+              {
+                  "id": "eth_information",
+                  "url": "http://localhost:8546",
+                  "name": "NewNodeName",
+                  "contact": "mynewemail@gmail.com"
+              }
+          ],
+          "transfers":[
+              {
+                  "id": "rest_transfer",
+                  "address": "http://localhost:4003",
+                  "identifier": "NewIdentifier",
+                  "secret": "newsecret"
+              }
+          ]
+      }
+  }
+
+  ```
+
+  The file can reside anywhere on the machine that the Elixir executable has access to.
+  The key/value pairs in the JSON configuration will replace the defaults specified in the Elixir configuration (i.e. `config/{dev,test,prod}.exs`).
+
+  ## Coverage
+
+  To get an HTML coverage report on your own machine try `env MIX_ENV=test mix coveralls.html` then open `cover/excoveralls.html`.
+  You can get a simple print-out with `env MIX_ENV=test mix coveralls`.
+
+  """
+
+end
\ No newline at end of file
diff --git a/mix.exs b/mix.exs
index 20f1b1e..97ad8b2 100644
--- a/mix.exs
+++ b/mix.exs
@@ -54,9 +54,13 @@ defmodule POAAgent.MixProject do
 
   defp docs do
     [
+      main: POAAgent,
       source_ref: "v#{@version}",
       source_url: "https://github.com/poanetwork/poa-netstats-agent",
-      extras: ["pages/initial_architecture.md": [filename: "initial_architecture", title: "Initial Architecture"]],
+      extras: [
+        "pages/initial_architecture.md": [filename: "initial_architecture", title: "Initial Architecture"],
+        "pages/starting_guide.md": [filename: "starting_guide", title: "Getting Started"]
+        ],
       groups_for_modules: [
         "Plugins": [
           POAAgent.Plugins.Collector,
diff --git a/pages/starting_guide.md b/pages/starting_guide.md
new file mode 100644
index 0000000..9225efa
--- /dev/null
+++ b/pages/starting_guide.md
@@ -0,0 +1,172 @@
+# Starting Guide
+
+With this guide we are going to go thru an example of how to set up the agent and connect with the `POA Warehouse`.
+
+# Brief introduction
+
+`POAAgent` is built on top of a Collector's Plugin Mechanism. You can add, remove and create your own one. We have developed some collectors but you can create your own ones. Check [how to implement a collector](POAAgent.Plugins.Collector.html).
+
+The `Collectors` send data to `Transfers`. A transfer is an Elixir process which will receive the data. You can implement your own Transfer, check [this](POAAgent.Plugins.Transfer.html). We have developed a transfer in order to send data to the [POA Warehouse](https://github.com/poanetwork/poa-netstats-warehouse).
+
+Every collector can send data to one or many different transfers. The mapping between collectors and Transfers is done in the config file.
+
+In our example we are going to add 4 collectors
+- Information Collector: This collector sends Ethereum info to the Transfers periodically.
+- Latest Block Collector: This collector "listens" the Ethereum node checking if a new block has been added. Once a new token is detected it will be sent to the mapped Transfers.
+- Stats Collector: This collector checks periodically the Ethereum node in order to see if the stats has changed. When changed it will send the data to the transfers.
+- Pending Transactions Collector: This collector checks with the Ethereum node if the value of "Pending Transactions" has changed, if that is the case it will send the data to the Transfers.
+
+## Setting up
+
+The collectors we want to use need an Ethereum node to monitor so we will need the host:port. In our example my Ethereum node is running in `http://localhost:8545`
+
+In order to configure the Agent we have to fill a config file. In this case we are going to call it `prod.exs`. We are going to fill it step by step:
+
+We have use the `Mix.Config` module, this is needed in every Elixir Config file.
+
+```
+use Mix.Config
+```
+
+Next we have to indicate the overlay configuration, you can check how that works [here](POAAgent.html#module-configuration) but in our case the `config_overlay.json` will remain without changes.
+
+```
+config :poa_agent,
+    config_overlay: "config/config_overlay.json"
+```
+
+Now we need the `Ethereumex` configuration. [Ethereumex](https://github.com/exthereum/ethereumex) is the Elixir library we are using to communicate with the Ethereum node. There we have to put the Ethereum url.
+
+```
+config :ethereumex,
+    url: "http://localhost:8545"
+```
+
+We also need the configuration for the Collectors, here we have to indicate the ones we are going to use.
+
+```
+config :poa_agent, 
+       :collectors,
+       [
+         {:eth_information, POAAgent.Plugins.Collectors.Eth.Information, 60_000, :eth_information, [url: "http://localhost:8545", name: "Elixir-NodeJS-Integration", contact: "myemail@gmail.com"]},
+         {:eth_latest_block, POAAgent.Plugins.Collectors.Eth.LatestBlock, 500, :latest_block, [url: "http://localhost:8545"]},
+         {:eth_stats, POAAgent.Plugins.Collectors.Eth.Stats, 5000, :eth_stats, [url: "http://localhost:8545"]},
+         {:eth_pending, POAAgent.Plugins.Collectors.Eth.Pending, 500, :eth_pending, [url: "http://localhost:8545"]}
+         
+       ]
+```
+
+You can check in the docs what each field mean in the configuration but it is quite straightforward.
+
+Now we are going to configure the Transfer information. For now we are not going to use transfers (we will check how to use the Warehouse transfer later).
+
+```
+config :poa_agent, 
+       :transfers,
+       [
+       ]
+```
+
+The last steps is configuring the mapping. Mapping is where we say to which Transfers each Collector is going to send the data. In our case is straightforward since we are not using Transfers
+
+```
+config :poa_agent,
+       :mappings,
+       [
+         {:eth_latest_block, []},
+         {:eth_stats, []},
+         {:eth_pending, []},
+         {:eth_information, []}
+       ]
+```
+
+with this configuration the agent must be able to start running the command
+
+```
+MIX_ENV=prod iex -S mix
+```
+
+`MIX_ENV=prod` sets a Environment variable used by mix to `prod`. We are using that variable for choosing the config files. That means we are going to use `prod.exs` as a configuration file.
+
+This will start the agent directly in the terminal. If you want to create a release you must read [this](POAAgent.html#module-building-deploying-an-executable)
+
+## Connecting to POA Warehouse
+
+In order to connect with POA Warehouse we have to use a Transfer which is aligned with the POA's protocol. We have developed a Transfer called `REST` which implements the REST version of the POA's protocol. In order to use it we have to declare it in the Config file.
+
+Let's update the `transfers` section in the `prod.exs` file
+
+```
+config :poa_agent, 
+       :transfers,
+       [
+         {:rest_transfer, POAAgent.Plugins.Transfers.HTTP.REST, [
+             address: "http://localhost:4002",
+             identifier: "elixirNodeJSIntegration",
+
+             # Authentication parameters
+             user: "",
+             password: "",
+             token_url: ""
+           ]
+         }
+       ]
+```
+
+Well, it seems we need some Auth parameters before starting the Agent. We need a valid user with a valid password and we also need a url in order to request JWT tokens
+
+First we will create a valid user/password. If you want to join POA's network you have to ask them for a new user/password. If you have access to the Warehouse you have to call the _create user_ endpoint.
+
+Let's assume we have access to the Warehouse and it is running in `https://localhost:4003`. We start asking for a user/password with a valid Admin user and Admin Password. The Admin is "admin1" and the password "password12345678". We can find the documentation about the user endpoint [here](https://rawgit.com/poanetwork/poa-netstats-warehouse/master/doc/POABackend.Auth.REST.html#module-user-endpoint).
+
+```
+curl -i -X POST -H "Authorization: Basic YWRtaW4xOnBhc3N3b3JkMTIzNDU2Nzg=" -H "Content-Type: application/json" https://localhost:4003/user --insecure
+
+HTTP/1.1 200 OK
+server: Cowboy
+date: Tue, 21 Aug 2018 00:18:29 GMT
+content-length: 53
+cache-control: max-age=0, private, must-revalidate
+
+{"user-name":"BK3eiZcT","password":"MPr1n9B-ipvpYbj"}
+```
+
+There we have our user name and password. We also know the token url is in `https://localhost:4003/session`. Now we have to update the config file.
+
+```
+config :poa_agent, 
+       :transfers,
+       [
+         {:rest_transfer, POAAgent.Plugins.Transfers.HTTP.REST, [
+             address: "http://localhost:4002",
+             identifier: "elixirNodeJSIntegration",
+
+             # Authentication parameters
+             user: "BK3eiZcT",
+             password: "MPr1n9B-ipvpYbj",
+             token_url: "https://localhost:4003/session"
+           ]
+         }
+       ]
+```
+
+We have more configuration to update. Since we have added a Transfer we have to send data to it, so we have to make all the collectors sending data to that `rest_transfer`
+
+```
+config :poa_agent,
+       :mappings,
+       [
+         {:eth_latest_block, [:rest_transfer]},
+         {:eth_stats, [:rest_transfer]},
+         {:eth_pending, [:rest_transfer]},
+         {:eth_information, [:rest_transfer]}
+       ]
+```
+
+Now we can stop the agent and start again.
+
+```
+MIX_ENV=prod iex -S mix
+```
+
+Now you will see in the Agent's terminal the transfer is requesting a token and sending data to the Warehouse.
\ No newline at end of file