[#71] Adding Getting Started guide
This commit is contained in:
Felipe Ripoll
parent
994f26dd78
commit
9632678c1b
|
|
@ -3,11 +3,10 @@
|
|||
[](https://coveralls.io/github/poanetwork/poa-netstats-agent?branch=master)
|
||||
[](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
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
]
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@
|
|||
<title>404 – poa_agent v0.1.0</title>
|
||||
<link rel="stylesheet" href="dist/app-480ffdc169.css" />
|
||||
|
||||
<script src="dist/sidebar_items-d9b3f5cff8.js"></script>
|
||||
<script src="dist/sidebar_items-303975f305.js"></script>
|
||||
|
||||
|
||||
|
||||
|
|
@ -29,7 +29,7 @@
|
|||
<section class="sidebar">
|
||||
|
||||
|
||||
<a href="api-reference.html" class="sidebar-projectLink">
|
||||
<a href="POAAgent.html" class="sidebar-projectLink">
|
||||
<div class="sidebar-projectDetails">
|
||||
<h1 class="sidebar-projectName">
|
||||
poa_agent
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@
|
|||
<title>POAAgent.Application – poa_agent v0.1.0</title>
|
||||
<link rel="stylesheet" href="dist/app-480ffdc169.css" />
|
||||
|
||||
<script src="dist/sidebar_items-d9b3f5cff8.js"></script>
|
||||
<script src="dist/sidebar_items-303975f305.js"></script>
|
||||
|
||||
|
||||
|
||||
|
|
@ -29,7 +29,7 @@
|
|||
<section class="sidebar">
|
||||
|
||||
|
||||
<a href="api-reference.html" class="sidebar-projectLink">
|
||||
<a href="POAAgent.html" class="sidebar-projectLink">
|
||||
<div class="sidebar-projectDetails">
|
||||
<h1 class="sidebar-projectName">
|
||||
poa_agent
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@
|
|||
<title>POAAgent.Entity.NameConvention – poa_agent v0.1.0</title>
|
||||
<link rel="stylesheet" href="dist/app-480ffdc169.css" />
|
||||
|
||||
<script src="dist/sidebar_items-d9b3f5cff8.js"></script>
|
||||
<script src="dist/sidebar_items-303975f305.js"></script>
|
||||
|
||||
|
||||
|
||||
|
|
@ -29,7 +29,7 @@
|
|||
<section class="sidebar">
|
||||
|
||||
|
||||
<a href="api-reference.html" class="sidebar-projectLink">
|
||||
<a href="POAAgent.html" class="sidebar-projectLink">
|
||||
<div class="sidebar-projectDetails">
|
||||
<h1 class="sidebar-projectName">
|
||||
poa_agent
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@
|
|||
<title>POAAgent.Format.POAProtocol.Data.Format – poa_agent v0.1.0</title>
|
||||
<link rel="stylesheet" href="dist/app-480ffdc169.css" />
|
||||
|
||||
<script src="dist/sidebar_items-d9b3f5cff8.js"></script>
|
||||
<script src="dist/sidebar_items-303975f305.js"></script>
|
||||
|
||||
|
||||
|
||||
|
|
@ -29,7 +29,7 @@
|
|||
<section class="sidebar">
|
||||
|
||||
|
||||
<a href="api-reference.html" class="sidebar-projectLink">
|
||||
<a href="POAAgent.html" class="sidebar-projectLink">
|
||||
<div class="sidebar-projectDetails">
|
||||
<h1 class="sidebar-projectName">
|
||||
poa_agent
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@
|
|||
<title>POAAgent.Plugins.Collector – poa_agent v0.1.0</title>
|
||||
<link rel="stylesheet" href="dist/app-480ffdc169.css" />
|
||||
|
||||
<script src="dist/sidebar_items-d9b3f5cff8.js"></script>
|
||||
<script src="dist/sidebar_items-303975f305.js"></script>
|
||||
|
||||
|
||||
|
||||
|
|
@ -29,7 +29,7 @@
|
|||
<section class="sidebar">
|
||||
|
||||
|
||||
<a href="api-reference.html" class="sidebar-projectLink">
|
||||
<a href="POAAgent.html" class="sidebar-projectLink">
|
||||
<div class="sidebar-projectDetails">
|
||||
<h1 class="sidebar-projectName">
|
||||
poa_agent
|
||||
|
|
@ -84,7 +84,7 @@
|
|||
<p>Defines a Collector Plugin.</p>
|
||||
<p>A Collector plugin will run in an independent process and will run the <code class="inline">collect/1</code>
|
||||
function in a given <code class="inline">frequency</code>.</p>
|
||||
<p><code class="inline">POAAgent</code> app reads the Collectors configuration from the <code class="inline">config.exs</code> file when bootstrap and will create a
|
||||
<p><a href="POAAgent.html"><code class="inline">POAAgent</code></a> app reads the Collectors configuration from the <code class="inline">config.exs</code> file when bootstrap and will create a
|
||||
process per each one of them. That configuration is referenced by :collectors key.</p>
|
||||
<pre><code class="elixir">config :poa_agent,
|
||||
:collectors,
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@
|
|||
<title>POAAgent.Plugins.Collectors.Eth.Information – poa_agent v0.1.0</title>
|
||||
<link rel="stylesheet" href="dist/app-480ffdc169.css" />
|
||||
|
||||
<script src="dist/sidebar_items-d9b3f5cff8.js"></script>
|
||||
<script src="dist/sidebar_items-303975f305.js"></script>
|
||||
|
||||
|
||||
|
||||
|
|
@ -29,7 +29,7 @@
|
|||
<section class="sidebar">
|
||||
|
||||
|
||||
<a href="api-reference.html" class="sidebar-projectLink">
|
||||
<a href="POAAgent.html" class="sidebar-projectLink">
|
||||
<div class="sidebar-projectDetails">
|
||||
<h1 class="sidebar-projectName">
|
||||
poa_agent
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@
|
|||
<title>POAAgent.Plugins.Collectors.Eth.LatestBlock – poa_agent v0.1.0</title>
|
||||
<link rel="stylesheet" href="dist/app-480ffdc169.css" />
|
||||
|
||||
<script src="dist/sidebar_items-d9b3f5cff8.js"></script>
|
||||
<script src="dist/sidebar_items-303975f305.js"></script>
|
||||
|
||||
|
||||
|
||||
|
|
@ -29,7 +29,7 @@
|
|||
<section class="sidebar">
|
||||
|
||||
|
||||
<a href="api-reference.html" class="sidebar-projectLink">
|
||||
<a href="POAAgent.html" class="sidebar-projectLink">
|
||||
<div class="sidebar-projectDetails">
|
||||
<h1 class="sidebar-projectName">
|
||||
poa_agent
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@
|
|||
<title>POAAgent.Plugins.Collectors.Eth.Pending – poa_agent v0.1.0</title>
|
||||
<link rel="stylesheet" href="dist/app-480ffdc169.css" />
|
||||
|
||||
<script src="dist/sidebar_items-d9b3f5cff8.js"></script>
|
||||
<script src="dist/sidebar_items-303975f305.js"></script>
|
||||
|
||||
|
||||
|
||||
|
|
@ -29,7 +29,7 @@
|
|||
<section class="sidebar">
|
||||
|
||||
|
||||
<a href="api-reference.html" class="sidebar-projectLink">
|
||||
<a href="POAAgent.html" class="sidebar-projectLink">
|
||||
<div class="sidebar-projectDetails">
|
||||
<h1 class="sidebar-projectName">
|
||||
poa_agent
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@
|
|||
<title>POAAgent.Plugins.Collectors.Eth.Stats – poa_agent v0.1.0</title>
|
||||
<link rel="stylesheet" href="dist/app-480ffdc169.css" />
|
||||
|
||||
<script src="dist/sidebar_items-d9b3f5cff8.js"></script>
|
||||
<script src="dist/sidebar_items-303975f305.js"></script>
|
||||
|
||||
|
||||
|
||||
|
|
@ -29,7 +29,7 @@
|
|||
<section class="sidebar">
|
||||
|
||||
|
||||
<a href="api-reference.html" class="sidebar-projectLink">
|
||||
<a href="POAAgent.html" class="sidebar-projectLink">
|
||||
<div class="sidebar-projectDetails">
|
||||
<h1 class="sidebar-projectName">
|
||||
poa_agent
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@
|
|||
<title>POAAgent.Plugins.Transfer – poa_agent v0.1.0</title>
|
||||
<link rel="stylesheet" href="dist/app-480ffdc169.css" />
|
||||
|
||||
<script src="dist/sidebar_items-d9b3f5cff8.js"></script>
|
||||
<script src="dist/sidebar_items-303975f305.js"></script>
|
||||
|
||||
|
||||
|
||||
|
|
@ -29,7 +29,7 @@
|
|||
<section class="sidebar">
|
||||
|
||||
|
||||
<a href="api-reference.html" class="sidebar-projectLink">
|
||||
<a href="POAAgent.html" class="sidebar-projectLink">
|
||||
<div class="sidebar-projectDetails">
|
||||
<h1 class="sidebar-projectName">
|
||||
poa_agent
|
||||
|
|
@ -84,7 +84,7 @@
|
|||
<p>Defines a Transfer Plugin.</p>
|
||||
<p>A Transfer plugin receives data from Collectors. It uses the Collector’s <code class="inline">label</code> in order to
|
||||
differenciate from multiple Collectors.</p>
|
||||
<p><code class="inline">POAAgent</code> app reads the Transfers configuration from the <code class="inline">config.exs</code> file when bootstrap and will create a
|
||||
<p><a href="POAAgent.html"><code class="inline">POAAgent</code></a> app reads the Transfers configuration from the <code class="inline">config.exs</code> file when bootstrap and will create a
|
||||
process per each one of them. That configuration is referenced by :transfers key.</p>
|
||||
<pre><code class="elixir">config :poa_agent,
|
||||
:transfers,
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@
|
|||
<title>POAAgent.Plugins.Transfers.WebSocket.Primus – poa_agent v0.1.0</title>
|
||||
<link rel="stylesheet" href="dist/app-480ffdc169.css" />
|
||||
|
||||
<script src="dist/sidebar_items-d9b3f5cff8.js"></script>
|
||||
<script src="dist/sidebar_items-303975f305.js"></script>
|
||||
|
||||
|
||||
|
||||
|
|
@ -29,7 +29,7 @@
|
|||
<section class="sidebar">
|
||||
|
||||
|
||||
<a href="api-reference.html" class="sidebar-projectLink">
|
||||
<a href="POAAgent.html" class="sidebar-projectLink">
|
||||
<div class="sidebar-projectDetails">
|
||||
<h1 class="sidebar-projectName">
|
||||
poa_agent
|
||||
|
|
|
|||
|
|
@ -0,0 +1,222 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="x-ua-compatible" content="ie=edge">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<meta name="generator" content="ExDoc v0.18.3">
|
||||
<title>POAAgent – poa_agent v0.1.0</title>
|
||||
<link rel="stylesheet" href="dist/app-480ffdc169.css" />
|
||||
|
||||
<script src="dist/sidebar_items-303975f305.js"></script>
|
||||
|
||||
|
||||
|
||||
|
||||
</head>
|
||||
<body data-type="modules">
|
||||
<script>try { if(localStorage.getItem('night-mode')) document.body.className += ' night-mode'; } catch (e) { }</script>
|
||||
|
||||
<div class="main">
|
||||
<button class="sidebar-button sidebar-toggle">
|
||||
<span class="icon-menu" aria-hidden="true"></span>
|
||||
<span class="sr-only">Toggle Sidebar</span>
|
||||
</button>
|
||||
<button class="sidebar-button night-mode-toggle">
|
||||
<span class="icon-theme" aria-hidden="true"></span>
|
||||
<span class="sr-only">Toggle Theme</span>
|
||||
</button>
|
||||
<section class="sidebar">
|
||||
|
||||
|
||||
<a href="POAAgent.html" class="sidebar-projectLink">
|
||||
<div class="sidebar-projectDetails">
|
||||
<h1 class="sidebar-projectName">
|
||||
poa_agent
|
||||
</h1>
|
||||
<h2 class="sidebar-projectVersion">
|
||||
v0.1.0
|
||||
</h2>
|
||||
</div>
|
||||
|
||||
</a>
|
||||
|
||||
<form class="sidebar-search" action="search.html">
|
||||
<button type="submit" class="search-button">
|
||||
<span class="icon-search" aria-hidden="true"></span>
|
||||
</button>
|
||||
<input name="q" type="text" id="search-list" class="search-input" placeholder="Search" aria-label="Search" autocomplete="off" />
|
||||
</form>
|
||||
|
||||
<ul class="sidebar-listNav">
|
||||
<li><a id="extras-list" href="#full-list">Pages</a></li>
|
||||
|
||||
|
||||
<li><a id="modules-list" href="#full-list">Modules</a></li>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
</ul>
|
||||
<div class="gradient"></div>
|
||||
<ul id="full-list" class="sidebar-fullList"></ul>
|
||||
</section>
|
||||
|
||||
<section class="content">
|
||||
<div class="content-outer">
|
||||
<div id="content" class="content-inner">
|
||||
|
||||
|
||||
<h1>
|
||||
<small class="visible-xs">poa_agent v0.1.0</small>
|
||||
POAAgent
|
||||
|
||||
<a href="https://github.com/poanetwork/poa-netstats-agent/blob/v0.1.0/lib/poa_agent.ex#L1" title="View Source" class="view-source" rel="help">
|
||||
<span class="icon-code" aria-hidden="true"></span>
|
||||
<span class="sr-only">View Source</span>
|
||||
</a>
|
||||
|
||||
</h1>
|
||||
|
||||
|
||||
<section id="moduledoc">
|
||||
<h1>POAAgent</h1>
|
||||
<p><a href="https://coveralls.io/github/poanetwork/poa-netstats-agent?branch=master"><img src="https://coveralls.io/repos/github/poanetwork/poa-netstats-agent/badge.svg?branch=master" alt="Coverage Status"/></a>
|
||||
<a href="https://codecov.io/gh/poanetwork/poa-netstats-agent"><img src="https://codecov.io/gh/poanetwork/poa-netstats-agent/branch/master/graph/badge.svg" alt="codecov"/></a></p>
|
||||
<h2 id="module-documentation" class="section-heading">
|
||||
<a href="#module-documentation" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
|
||||
Documentation
|
||||
</h2>
|
||||
|
||||
<ul>
|
||||
<li><a href="pages/initial_architecture.md">Initial Architecture</a>
|
||||
</li>
|
||||
<li>You can find the online documentation <a href="https://rawgit.com/poanetwork/poa-netstats-agent/master/doc/index.html">here</a>
|
||||
</li>
|
||||
<li><a href="starting_guide.html">Getting Started</a>
|
||||
</li>
|
||||
</ul>
|
||||
<p>Or you can build the documenation locally running</p>
|
||||
<pre><code class="elixir">mix deps.get
|
||||
mix docs</code></pre>
|
||||
<p>That command will create a <code class="inline">doc/</code> folder with the actual Documentation.</p>
|
||||
<h2 id="module-run" class="section-heading">
|
||||
<a href="#module-run" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
|
||||
Run
|
||||
</h2>
|
||||
|
||||
<p>POAAgent is an Elixir application, in order to run it first we need to fetch the dependencies and compile it.</p>
|
||||
<pre><code class="elixir">mix deps.get
|
||||
mix deps.compile
|
||||
mix compile</code></pre>
|
||||
<p>To run the Elixir application while under development it may be convenient to use:
|
||||
<code class="inline">env MIX_ENV=dev mix run --no-halt</code> with an appropiate configuration in <code class="inline">/config/dev.exs</code>.</p>
|
||||
<h2 id="module-run-tests" class="section-heading">
|
||||
<a href="#module-run-tests" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
|
||||
Run Tests
|
||||
</h2>
|
||||
|
||||
<p>In order to run the tests we have to run the command</p>
|
||||
<pre><code class="elixir">mix test</code></pre>
|
||||
<p><a href="POAAgent.html#content"><code class="inline">POAAgent</code></a> comes also with a code analysis tool <a href="https://github.com/rrrene/credo">Credo</a> and a types checker tool <a href="https://github.com/jeremyjh/dialyxir">Dialyxir</a>. In order to run them we have to run</p>
|
||||
<pre><code class="elixir">mix credo
|
||||
mix dialyzer</code></pre>
|
||||
<h2 id="module-building-deploying-an-executable" class="section-heading">
|
||||
<a href="#module-building-deploying-an-executable" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
|
||||
Building & Deploying an Executable
|
||||
</h2>
|
||||
|
||||
<p>To build an executable you’ll need Elixir 1.6 (and Erlang/OTP 20).</p>
|
||||
<ol>
|
||||
<li>Once you have a copy of this repository configure the agent for production in the file <code class="inline">config/prod.exs</code>.
|
||||
</li>
|
||||
<li>An real configuration example can be found in the default <code class="inline">config/prod.exs</code>.
|
||||
</li>
|
||||
<li>Do a <code class="inline">mix deps.get</code> to fetch, among other dependencies, the tooling for building server executables.
|
||||
</li>
|
||||
<li>A <code class="inline">env MIX_ENV=prod mix release --name=poa_agent --env=prod</code> will assemble an executable.
|
||||
</li>
|
||||
</ol>
|
||||
<p>A resulting artifact resides at <code class="inline">_build/prod/rel/poa_agent/releases/0.1.0/poa_agent.tar.gz</code> which you can move to a remote host.
|
||||
Use <code class="inline">tar xfz</code> then <code class="inline">bin/poa_agent start</code> (<code class="inline">bin/poa_agent stop</code> will stop the server cleanly).</p>
|
||||
<p>If you want to run it on the local host then the procedure is as simple as: <code class="inline">_build/prod/rel/poa_agent/bin/poa_agent</code>.</p>
|
||||
<p><strong>Note:</strong> 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 <code class="inline">https://hexdocs.pm/distillery/getting-started.html</code>).</p>
|
||||
<h2 id="module-configuration" class="section-heading">
|
||||
<a href="#module-configuration" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
|
||||
Configuration
|
||||
</h2>
|
||||
|
||||
<p>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 <code class="inline">config_overlay</code> key/value.
|
||||
The following is an extract from <a href="config/test.exs">config/test.exs</a>:</p>
|
||||
<pre><code class="Elixir">config :poa_agent,
|
||||
config_overlay: "config/config_overlay.json"</code></pre>
|
||||
<p>A corresponding example is provided in <code class="inline">config/config_overlay.json</code>:</p>
|
||||
<pre><code class="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"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
</code></pre>
|
||||
<p>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. <code class="inline">config/{dev,test,prod}.exs</code>).</p>
|
||||
<h2 id="module-coverage" class="section-heading">
|
||||
<a href="#module-coverage" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
|
||||
Coverage
|
||||
</h2>
|
||||
|
||||
<p>To get an HTML coverage report on your own machine try <code class="inline">env MIX_ENV=test mix coveralls.html</code> then open <code class="inline">cover/excoveralls.html</code>.
|
||||
You can get a simple print-out with <code class="inline">env MIX_ENV=test mix coveralls</code>.</p>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<footer class="footer">
|
||||
<p>
|
||||
<span class="line">
|
||||
Built using
|
||||
<a href="https://github.com/elixir-lang/ex_doc" title="ExDoc" rel="help" target="_blank">ExDoc</a> (v0.18.3),
|
||||
</span>
|
||||
<span class="line">
|
||||
designed by
|
||||
<a href="https://twitter.com/dignifiedquire" target="_blank" title="@dignifiedquire">Friedel Ziegelmayer</a>.
|
||||
</span>
|
||||
</p>
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script src="dist/app-9bd040e5e5.js"></script>
|
||||
|
||||
|
||||
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
||||
|
|
@ -8,7 +8,7 @@
|
|||
<title>API Reference – poa_agent v0.1.0</title>
|
||||
<link rel="stylesheet" href="dist/app-480ffdc169.css" />
|
||||
|
||||
<script src="dist/sidebar_items-d9b3f5cff8.js"></script>
|
||||
<script src="dist/sidebar_items-303975f305.js"></script>
|
||||
|
||||
|
||||
|
||||
|
|
@ -29,7 +29,7 @@
|
|||
<section class="sidebar">
|
||||
|
||||
|
||||
<a href="api-reference.html" class="sidebar-projectLink">
|
||||
<a href="POAAgent.html" class="sidebar-projectLink">
|
||||
<div class="sidebar-projectDetails">
|
||||
<h1 class="sidebar-projectName">
|
||||
poa_agent
|
||||
|
|
@ -82,6 +82,13 @@
|
|||
|
||||
<div class="summary">
|
||||
<div class="summary-row">
|
||||
<div class="summary-signature"><a href="POAAgent.html">POAAgent</a></div>
|
||||
|
||||
<div class="summary-synopsis"><h1>POAAgent</h1>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
<div class="summary-row">
|
||||
<div class="summary-signature"><a href="POAAgent.Application.html">POAAgent.Application</a></div>
|
||||
|
||||
<div class="summary-synopsis"><p>This module implements the Application behaviour</p>
|
||||
|
|
|
|||
|
|
@ -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":[]}
|
||||
|
|
@ -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":[]}
|
||||
|
|
@ -3,7 +3,7 @@
|
|||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>poa_agent v0.1.0 – Documentation</title>
|
||||
<meta http-equiv="refresh" content="0; url=api-reference.html">
|
||||
<meta http-equiv="refresh" content="0; url=POAAgent.html">
|
||||
<meta name="robots" content="noindex">
|
||||
<meta name="generator" content="ExDoc v0.18.3">
|
||||
</head>
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@
|
|||
<title>Initial Architecture – poa_agent v0.1.0</title>
|
||||
<link rel="stylesheet" href="dist/app-480ffdc169.css" />
|
||||
|
||||
<script src="dist/sidebar_items-d9b3f5cff8.js"></script>
|
||||
<script src="dist/sidebar_items-303975f305.js"></script>
|
||||
|
||||
|
||||
|
||||
|
|
@ -29,7 +29,7 @@
|
|||
<section class="sidebar">
|
||||
|
||||
|
||||
<a href="api-reference.html" class="sidebar-projectLink">
|
||||
<a href="POAAgent.html" class="sidebar-projectLink">
|
||||
<div class="sidebar-projectDetails">
|
||||
<h1 class="sidebar-projectName">
|
||||
poa_agent
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@
|
|||
<title>Search – poa_agent v0.1.0</title>
|
||||
<link rel="stylesheet" href="dist/app-480ffdc169.css" />
|
||||
|
||||
<script src="dist/sidebar_items-d9b3f5cff8.js"></script>
|
||||
<script src="dist/sidebar_items-303975f305.js"></script>
|
||||
|
||||
|
||||
|
||||
|
|
@ -29,7 +29,7 @@
|
|||
<section class="sidebar">
|
||||
|
||||
|
||||
<a href="api-reference.html" class="sidebar-projectLink">
|
||||
<a href="POAAgent.html" class="sidebar-projectLink">
|
||||
<div class="sidebar-projectDetails">
|
||||
<h1 class="sidebar-projectName">
|
||||
poa_agent
|
||||
|
|
|
|||
|
|
@ -0,0 +1,216 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="x-ua-compatible" content="ie=edge">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<meta name="generator" content="ExDoc v0.18.3">
|
||||
<title>Getting Started – poa_agent v0.1.0</title>
|
||||
<link rel="stylesheet" href="dist/app-480ffdc169.css" />
|
||||
|
||||
<script src="dist/sidebar_items-303975f305.js"></script>
|
||||
|
||||
|
||||
|
||||
|
||||
</head>
|
||||
<body data-type="extras">
|
||||
<script>try { if(localStorage.getItem('night-mode')) document.body.className += ' night-mode'; } catch (e) { }</script>
|
||||
|
||||
<div class="main">
|
||||
<button class="sidebar-button sidebar-toggle">
|
||||
<span class="icon-menu" aria-hidden="true"></span>
|
||||
<span class="sr-only">Toggle Sidebar</span>
|
||||
</button>
|
||||
<button class="sidebar-button night-mode-toggle">
|
||||
<span class="icon-theme" aria-hidden="true"></span>
|
||||
<span class="sr-only">Toggle Theme</span>
|
||||
</button>
|
||||
<section class="sidebar">
|
||||
|
||||
|
||||
<a href="POAAgent.html" class="sidebar-projectLink">
|
||||
<div class="sidebar-projectDetails">
|
||||
<h1 class="sidebar-projectName">
|
||||
poa_agent
|
||||
</h1>
|
||||
<h2 class="sidebar-projectVersion">
|
||||
v0.1.0
|
||||
</h2>
|
||||
</div>
|
||||
|
||||
</a>
|
||||
|
||||
<form class="sidebar-search" action="search.html">
|
||||
<button type="submit" class="search-button">
|
||||
<span class="icon-search" aria-hidden="true"></span>
|
||||
</button>
|
||||
<input name="q" type="text" id="search-list" class="search-input" placeholder="Search" aria-label="Search" autocomplete="off" />
|
||||
</form>
|
||||
|
||||
<ul class="sidebar-listNav">
|
||||
<li><a id="extras-list" href="#full-list">Pages</a></li>
|
||||
|
||||
|
||||
<li><a id="modules-list" href="#full-list">Modules</a></li>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
</ul>
|
||||
<div class="gradient"></div>
|
||||
<ul id="full-list" class="sidebar-fullList"></ul>
|
||||
</section>
|
||||
|
||||
<section class="content">
|
||||
<div class="content-outer">
|
||||
<div id="content" class="content-inner">
|
||||
|
||||
|
||||
<h1>Starting Guide</h1>
|
||||
<p>With this guide we are going to go thru an example of how to set up the agent and connect with the <code class="inline">POA Warehouse</code>.</p>
|
||||
<h1>Brief introduction</h1>
|
||||
<p><a href="POAAgent.html"><code class="inline">POAAgent</code></a> 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 <a href="POAAgent.Plugins.Collector.html">how to implement a collector</a>.</p>
|
||||
<p>The <code class="inline">Collectors</code> send data to <code class="inline">Transfers</code>. A transfer is an Elixir process which will receive the data. You can implement your own Transfer, check <a href="POAAgent.Plugins.Transfer.html">this</a>. We have developed a transfer in order to send data to the <a href="https://github.com/poanetwork/poa-netstats-warehouse">POA Warehouse</a>.</p>
|
||||
<p>Every collector can send data to one or many different transfers. The mapping between collectors and Transfers is done in the config file.</p>
|
||||
<p>In our example we are going to add 4 collectors</p>
|
||||
<ul>
|
||||
<li>Information Collector: This collector sends Ethereum info to the Transfers periodically.
|
||||
</li>
|
||||
<li>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.
|
||||
</li>
|
||||
<li>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.
|
||||
</li>
|
||||
<li>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.
|
||||
</li>
|
||||
</ul>
|
||||
<h2 id="setting-up" class="section-heading">
|
||||
<a href="#setting-up" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
|
||||
Setting up
|
||||
</h2>
|
||||
|
||||
<p>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 <code class="inline">http://localhost:8545</code></p>
|
||||
<p>In order to configure the Agent we have to fill a config file. In this case we are going to call it <code class="inline">prod.exs</code>. We are going to fill it step by step:</p>
|
||||
<p>We have use the <a href="https://hexdocs.pm/mix/Mix.Config.html"><code class="inline">Mix.Config</code></a> module, this is needed in every Elixir Config file.</p>
|
||||
<pre><code class="elixir">use Mix.Config</code></pre>
|
||||
<p>Next we have to indicate the overlay configuration, you can check how that works <a href="POAAgent.html#module-configuration">here</a> but in our case the <code class="inline">config_overlay.json</code> will remain without changes.</p>
|
||||
<pre><code class="elixir">config :poa_agent,
|
||||
config_overlay: "config/config_overlay.json"</code></pre>
|
||||
<p>Now we need the <code class="inline">Ethereumex</code> configuration. <a href="https://github.com/exthereum/ethereumex">Ethereumex</a> is the Elixir library we are using to communicate with the Ethereum node. There we have to put the Ethereum url.</p>
|
||||
<pre><code class="elixir">config :ethereumex,
|
||||
url: "http://localhost:8545"</code></pre>
|
||||
<p>We also need the configuration for the Collectors, here we have to indicate the ones we are going to use.</p>
|
||||
<pre><code class="elixir">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"]}
|
||||
|
||||
]</code></pre>
|
||||
<p>You can check in the docs what each field mean in the configuration but it is quite straightforward.</p>
|
||||
<p>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).</p>
|
||||
<pre><code class="elixir">config :poa_agent,
|
||||
:transfers,
|
||||
[
|
||||
]</code></pre>
|
||||
<p>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</p>
|
||||
<pre><code class="elixir">config :poa_agent,
|
||||
:mappings,
|
||||
[
|
||||
{:eth_latest_block, []},
|
||||
{:eth_stats, []},
|
||||
{:eth_pending, []},
|
||||
{:eth_information, []}
|
||||
]</code></pre>
|
||||
<p>with this configuration the agent must be able to start running the command</p>
|
||||
<pre><code class="elixir">MIX_ENV=prod iex -S mix</code></pre>
|
||||
<p><code class="inline">MIX_ENV=prod</code> sets a Environment variable used by mix to <code class="inline">prod</code>. We are using that variable for choosing the config files. That means we are going to use <code class="inline">prod.exs</code> as a configuration file.</p>
|
||||
<p>This will start the agent directly in the terminal. If you want to create a release you must read <a href="POAAgent.html#module-building-deploying-an-executable">this</a></p>
|
||||
<h2 id="connecting-to-poa-warehouse" class="section-heading">
|
||||
<a href="#connecting-to-poa-warehouse" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
|
||||
Connecting to POA Warehouse
|
||||
</h2>
|
||||
|
||||
<p>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 <code class="inline">REST</code> which implements the REST version of the POA’s protocol. In order to use it we have to declare it in the Config file.</p>
|
||||
<p>Let’s update the <code class="inline">transfers</code> section in the <code class="inline">prod.exs</code> file</p>
|
||||
<pre><code class="elixir">config :poa_agent,
|
||||
:transfers,
|
||||
[
|
||||
{:rest_transfer, POAAgent.Plugins.Transfers.HTTP.REST, [
|
||||
address: "http://localhost:4002",
|
||||
identifier: "elixirNodeJSIntegration",
|
||||
|
||||
# Authentication parameters
|
||||
user: "",
|
||||
password: "",
|
||||
token_url: ""
|
||||
]
|
||||
}
|
||||
]</code></pre>
|
||||
<p>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</p>
|
||||
<p>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 <em>create user</em> endpoint.</p>
|
||||
<p>Let’s assume we have access to the Warehouse and it is running in <code class="inline">https://localhost:4003</code>. 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 <a href="https://rawgit.com/poanetwork/poa-netstats-warehouse/master/doc/POABackend.Auth.REST.html#module-user-endpoint">here</a>.</p>
|
||||
<pre><code class="elixir">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"}</code></pre>
|
||||
<p>There we have our user name and password. We also know the token url is in <code class="inline">https://localhost:4003/session</code>. Now we have to update the config file.</p>
|
||||
<pre><code class="elixir">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"
|
||||
]
|
||||
}
|
||||
]</code></pre>
|
||||
<p>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 <code class="inline">rest_transfer</code></p>
|
||||
<pre><code class="elixir">config :poa_agent,
|
||||
:mappings,
|
||||
[
|
||||
{:eth_latest_block, [:rest_transfer]},
|
||||
{:eth_stats, [:rest_transfer]},
|
||||
{:eth_pending, [:rest_transfer]},
|
||||
{:eth_information, [:rest_transfer]}
|
||||
]</code></pre>
|
||||
<p>Now we can stop the agent and start again.</p>
|
||||
<pre><code class="elixir">MIX_ENV=prod iex -S mix</code></pre>
|
||||
<p>Now you will see in the Agent’s terminal the transfer is requesting a token and sending data to the Warehouse.</p>
|
||||
|
||||
<footer class="footer">
|
||||
<p>
|
||||
<span class="line">
|
||||
Built using
|
||||
<a href="https://github.com/elixir-lang/ex_doc" title="ExDoc" rel="help" target="_blank">ExDoc</a> (v0.18.3),
|
||||
</span>
|
||||
<span class="line">
|
||||
designed by
|
||||
<a href="https://twitter.com/dignifiedquire" target="_blank" title="@dignifiedquire">Friedel Ziegelmayer</a>.
|
||||
</span>
|
||||
</p>
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script src="dist/app-9bd040e5e5.js"></script>
|
||||
|
||||
|
||||
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
||||
|
|
@ -0,0 +1,117 @@
|
|||
defmodule POAAgent do
|
||||
|
||||
@moduledoc """
|
||||
# POAAgent
|
||||
|
||||
[](https://coveralls.io/github/poanetwork/poa-netstats-agent?branch=master)
|
||||
[](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
|
||||
6
mix.exs
6
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,
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue