Backend setup

The backend system is currently made of these free and open source software components:

  • Kotori, a data acquisition, graphing and telemetry toolkit
  • InfluxDB, a time-series database
  • Grafana, a graph and dashboard builder for visualizing time series metrics
  • Eclipse Mosquitto, a MQTT message broker

It can be installed in various ways and will definitively work on Linux and other Unix-based systems, but maybe also on Windows. However, the documentation currently is just for Linux systems running the Debian distribution or derivatives like Ubuntu. Please get back to us if you need support for running it in different environments, we are happy to help.

Setup on Debian


Introduction

Install the whole stack on a Debian-based system.

All software packages are available from our package servers to make the installation a breeze. The package repository supports the architectures amd64 (Intel, AMD and x86-compatibles) and ARM (armhf), so it should work out of the box on Intel-compatible, RaspberryPi and similar hardware.

Prerequisites

Add GPG key for checking package signatures:

wget -qO - https://packages.hiveeyes.org/hiveeyes/foss/debian/pubkey.txt | apt-key add -

Add https addon for apt:

apt-get install apt-transport-https

Register package repository

Add package server (e.g. append to /etc/apt/sources.list):

deb https://packages.hiveeyes.org/hiveeyes/foss/debian/ testing main foundation

Reindex the package database:

apt-get update

Setup the whole software stack

# Install all packages at once
apt-get install kotori influxdb grafana mosquitto mosquitto-clients

# InfluxDB is not running after setup
systemctl start influxdb

Note

We recommend having the correct date and time configured on the backend system, otherwise you might experience glitches when accessing data in the past or in the future through Grafana. So please consider doing apt-get install chrony for setting up time synchronization on your backend machine.

Getting started

Access Grafana

Grafana is listening on TCP port 3000.

Configure Kotori vendor

  • cp /etc/kotori/examples/vendors/hiveeyes.ini /etc/kotori/apps-available/
    
  • Activate:

    ln -s /etc/kotori/apps-available/hiveeyes.ini /etc/kotori/apps-enabled/
    
  • Watch Kotori logfile:

    tail -F /var/log/kotori/kotori.log
    
  • Restart Kotori:

    systemctl restart kotori
    

Send sample measurements

MQTT

Please follow at How to send telemetry data using MQTT and use the hostname the backend system is running on:

export BROKER=backend.example.org

HTTP

To send telemetry data using HTTP, see How to send telemetry data using HTTP and use the hostname the backend system is running on:

export HTTPURI=http://backend.example.org:24642/api

Note

After installation, Kotori listens to localhost only. For making Kotori bind to all interfaces, effectively making it available to the public network, put the following bit of configuration into /etc/kotori/kotori.ini:

[kotori]
http_listen = 0.0.0.0

Watch telemetry data

Just navigate to the Grafana dashboard at http://backend.example.org:3000/dashboard/db/testdrive. When sending telemetry data using one of the examples above, you should see data being received and displayed instantly.

Appendix

See also

This is the Hiveeyes version of Kotori on Debian, with all dependencies.

Todo

Add description about how to run an Nginx- or Apache-based reverse proxy in front of Kotori and Grafana.