Boodskap IoT Platform

An Enterprise IoT Platform that helps to quickly connect with hardware devices, systems and backends to build solutions rapidly and robustly.

Get Started

Single Machine Installation

Installing Everything In a Single Machine

This installation instruction has been verified on Ubuntu 18.04. Generally it should work with *nix like OS if you know how to equate the commands to install the appropriate software packages

Perform the following actions as root or sudo access

sudo apt-get -y update
sudo apt-get -y update && apt-get install -y nginx sudo nodejs npm git software-properties-common netcat tar curl net-tools nano wget unzip rsyslog psmisc
sudo npm install pm2 -g

Install JDK 8 and 14

You can follow the instructions here for JDK 8

You can follow the instructions here for JDK 14

Generally you could download the archive files and extract into the /opt folder. Since we need both JDK 8 and 13, it's a good idea to keep it simple and separate. Make sure your installation method have the ability to point to the right JDK installation for the right software service below.

sudo add-apt-repository -y ppa:openjdk-r/ppa
sudo apt-get update -y
sudo apt-get install -y openjdk-8-jdk
sudo apt-get install -y openjdk-13-jdk

Also for process separation, we are going to create 6 different users for each software.

sudo adduser --disabled-password --gecos ""  boodskap
sudo adduser --disabled-password --gecos ""  boodskapui
sudo adduser --disabled-password --gecos ""  elastic
sudo adduser --disabled-password --gecos ""  cassandra
sudo adduser --disabled-password --gecos ""  emqtt
sudo adduser --disabled-password --gecos ""  kibana

🚧

Limits Tuning

Create a new file /etc/security/limits.d/21-limits.conf with the below content

*      soft   nofile      1048576
*      hard   nofile      1048576

🚧

System Parameters Tuning

Create a new file /etc/sysctl.d/99-z01-sysctl.conf with the below content

fs.file-max=2097152
fs.nr_open=2097152
net.core.somaxconn=32768
net.ipv4.tcp_max_syn_backlog=16384
net.core.netdev_max_backlog=16384
net.ipv4.ip_local_port_range=1024 65535
net.core.rmem_default=262144
net.core.wmem_default=262144
net.core.rmem_max=16777216
net.core.wmem_max=16777216
net.core.optmem_max=16777216

net.ipv4.tcp_mem=16777216 16777216 16777216
# net.ipv4.tcp_rmem=1024 4096 16777216
# net.ipv4.tcp_wmem=1024 4096 16777216
net.nf_conntrack_max=1000000
net.netfilter.nf_conntrack_max=1000000
net.netfilter.nf_conntrack_tcp_timeout_time_wait=30
net.ipv4.tcp_max_tw_buckets=1048576

# Enable fast recycling of TIME_WAIT sockets.  Enabling this
# option is not recommended for devices communicating with the
# general Internet or using NAT (Network Address Translation).
# Since some NAT gateways pass through IP timestamp values, one
# IP can appear to have non-increasing timestamps.
# net.ipv4.tcp_tw_recycle = 1
# net.ipv4.tcp_tw_reuse = 1
net.ipv4.tcp_fin_timeout = 15

vm.dirty_writeback_centisecs=500
vm.swappiness=10
vm.zone_reclaim_mode=0
vm.extra_free_kbytes=1240000

vm.max_map_count = 262144

Reboot the system and proceed with the installation

Installing Cassandra

Login as cassandra user and perform these tasks.

sudo su - cassandra

First time, edit the $HOME/.bash_profile file and enter the below contents

JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
PATH=$JAVA_HOME/bin:$PATH
export JAVA_HOME PATH
Now logout and login again
logout
sudo su - cassandra
cd $HOME
wget https://archive.apache.org/dist/cassandra/3.11.5/apache-cassandra-3.11.5-bin.tar.gz
tar -xzf apache-cassandra-3.11.5-bin.tar.gz
mv $HOME/apache-cassandra-3.11.5/* .
rm -rf $HOME/apache-cassandra-3.11.5*

Start the Cassandra service

$HOME/bin/cassandra

Create the keyspace.

$HOME/bin/cqlsh
CREATE KEYSPACE IF NOT EXISTS boodskapks WITH REPLICATION={ 'class' : 'SimpleStrategy', 'replication_factor' : 1 };

Installing Elastic Search

Login as elastic user and perform these tasks

sudo su - elastic

First time, edit the $HOME/.bash_profile file and enter the below contents.

JAVA_HOME=/usr/lib/jvm/java-13-openjdk-amd64
PATH=$JAVA_HOME/bin:$PATH
export JAVA_HOME PATH
Now logout and login again and perform the below.
cd $HOME
wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-7.5.1-linux-x86_64.tar.gz
tar -xzf elasticsearch-7.5.1-linux-x86_64.tar.gz
mv elasticsearch-7.5.1/* $HOME/
rm -rf $HOME/elasticsearch-7.5.1*

Start the Elastic Search service in background

$HOME/bin/elasticsearch &

🚧

If you run out of max shards open in elastic, you can dynamically increase it by

curl -X PUT elastic_host_or_ip:9200/_cluster/settings -H 'Content-type: application/json' --data-binary $'{"transient":{"cluster.max_shards_per_node":NUMBER_OF_SHARDS}}'
curl -X PUT elastic_host_or_ip:9200/_cluster/settings -H 'Content-type: application/json' --data-binary $'{"persistent":{"cluster.max_shards_per_node":NUMBER_OF_SHARDS}}'

Installing Kibana (Optional)

πŸ“˜

Kibana

Kibana is optional service, but we recommend to install it, it comes in very handy to practice elasticsearch queries on the fly

Login as kibana user and perform these tasks

sudo su - kibana

First time, edit the $HOME/.bash_profile file and enter the below contents.

JAVA_HOME=/usr/lib/jvm/java-13-openjdk-amd64
PATH=$JAVA_HOME/bin:$PATH
export JAVA_HOME PATH
Now logout and login again and perform the below.
cd $HOME
wget https://artifacts.elastic.co/downloads/kibana/kibana-7.5.1-linux-x86_64.tar.gz
tar -xzf kibana-7.5.1-linux-x86_64.tar.gz
mv kibana-7.5.1-linux-x86_64/* $HOME/
rm -rf $HOME/kibana-7.5.1-linux-x86_64

Start the Kibana Search service in background

$HOME/bin/kibana &

Installing EMQX

Login as emqtt user and perform these tasks

sudo su - emqtt
cd $HOME
wget --no-check-certificate  https://www.emqx.io/downloads/broker/v3.2.7/emqx-ubuntu18.04-v3.2.7.zip
unzip emqx-ubuntu18.04-v3.2.7.zip
mv emqx/* $HOME/
rm -rf $HOME/emqx
rm $HOME/emqx-ubuntu18.04-v3.2.7.zip
echo "{emqx_auth_http, true}." >> $HOME/data/loaded_plugins

πŸ‘

Configuring Authentication

Replace $HOME/etc/plugins/emqx_auth_http.conf file with the below contents

##--------------------------------------------------------------------
## HTTP Auth/ACL Plugin
##--------------------------------------------------------------------

## Authentication request.
##
## Variables:
##  - %u: username
##  - %c: clientid
##  - %a: ipaddress
##  - %l: accept port
##  - %P: password
##  - %C: common name of client TLS cert
##  - %d: subject of client TLS cert
##

auth.http.auth_req = http://localhost:18080/api/emqtt/get/auth
auth.http.auth_req.method = get
auth.http.auth_req.params = clientid=%c,username=%u,password=%P,ipaddr=%a

##--------------------------------------------------------------------
## Superuser request.
##
## Variables:
##  - %u: username
##  - %c: clientid
##  - %a: ipaddress
##  - %l: accept port
##  - %P: password
##  - %C: common name of client TLS cert
##  - %d: subject of client TLS cert
##
auth.http.super_req = http://localhost:18080/api/emqtt/get/superuser
auth.http.super_req.method = get
auth.http.super_req.params = clientid=%c,username=%u,ipaddr=%a

##--------------------------------------------------------------------
## ACL request.
##
## Variables:
##  - %A: 1 | 2, 1 = sub, 2 = pub
##  - %u: username
##  - %c: clientid
##  - %a: ipaddress
##  - %l: accept port
##  - %m: mountpoint
##  - %t: topic
##
auth.http.acl_req = http://localhost:18080/api/emqtt/acl
auth.http.acl_req.method = get
auth.http.acl_req.params = access=%A,username=%u,clientid=%c,ipaddr=%a,topic=%t

##------------------------------------------------------------------------------
## Http Reqeust options

## Time-out time for the http request, 0 is never timeout.
##
## Value: Duration
## -h: hour, e.g. '2h' for 2 hours
## -m: minute, e.g. '5m' for 5 minutes
## -s: second, e.g. '30s' for 30 seconds
##
## Default: 0
## auth.http.request.timeout = 0

## Connection time-out time, used during the initial request
## when the client is connecting to the server
##
## Value: Duration
##
## Default is same with the timeout option
## auth.http.request.connect_timout = 0

## Re-send http reuqest times
##
## Value: integer
##
## Default: 3
auth.http.request.retry_times = 3

## The interval for re-sending the http request
##
## Value: Duration
##
## Default: 1s
auth.http.request.retry_interval = 1s

## The 'Exponential Backoff' mechanism for re-sending request. The actually
## re-send time interval is `interval * backoff ^ times`
##
## Value: float
##
## Default: 2.0
auth.http.request.retry_backoff = 2.0

Start the Emqx service

$HOME/bin/emqx start

Boodskap Platform Installation

Login as boodskap user and perform these tasks

sudo su - boodskap

First time, edit the $HOME/.bash_profile file and enter the below contents.

JAVA_HOME=/usr/lib/jvm/java-13-openjdk-amd64
BOODSKAP_HOME=$HOME
PATH=$JAVA_HOME/bin:$BOODSKAP_HOME/bin:$PATH
export JAVA_HOME BOODSKAP_HOME PATH
Now **logout and login** again and perform the below.
cd $HOME
wget --no-check-certificate https://archive.apache.org/dist/ignite/2.8.0/apache-ignite-2.8.0-bin.zip
unzip apache-ignite-2.8.0-bin.zip
mv apache-ignite-2.8.0-bin/* $HOME/
rm -rf $HOME/apache-ignite-2.8.0-bin*
mv $HOME/config $HOME/config-old
wget --no-check-certificate https://github.com/BoodskapPlatform/boodskap-platform/releases/download/3.0.1/boodskap-all-libs-3.0.1.tar.gz
tar -xzf boodskap-all-libs-3.0.1.tar.gz

wget --no-check-certificate https://github.com/BoodskapPlatform/boodskap-platform/releases/download/3.0.1/boodskap-patch-3.0.1-10008.tar.gz
tar -xzf boodskap-patch-3.0.1-10008.tar.gz

Start the platform as background service.

$HOME/bin/ignite.sh -f $HOME/config/cluster.xml &

First Time Activation

$HOME/bin/control.sh --activate

Some times, the initialization may get stuck, if you don't see console logs not progressing, please restart the platform and you should be good.

killall java && sleep 10 && killall -KILL java
$HOME/bin/ignite.sh -f $HOME/config/cluster.xml &

Once the initialization is over, you should see something like this in your console.

2020-04-18 09:11:59.620 INFO  BootstrapService:195 -


    )             (           )
 ( /(             )\ )     ( /(     )
 )\())  (    (   (()/( (   )\()) ( /(  `  )
((_)\   )\   )\   ((_)))\ ((_)\  )(_)) /(/(
| |(_) ((_) ((_)  _| |((_)| |(_)((_)_ ((_)_\
| '_ \/ _ \/ _ \/ _` |(_-<| / / / _` || '_ \)
|_.__/\___/\___/\__,_|/__/|_\_\ \__,_|| .__/
                                      |_| IoT Platform


>>> ver. 3.0.1 - build(10002)
>>> 2020 Copyright(C) Boodskap Inc
>>>
>>> Boodskap documentation: http://developer.boodskap.io

You can access the platform's API at http://localhost:18080

Boodskap UI Installation

Login as boodskapui user and perform these tasks

sudo su - boodskapui
mkdir $HOME/webapps
cd $HOME/webapps
git clone https://github.com/BoodskapPlatform/boodskap-ui.git
cd $HOME/webapps/boodskap-ui
git checkout tags/v3.0.2
npm install
node build.js

Start the platform UI

pm2 start boodskap-platform-node.js

You can access the platform's dashboard at http://localhost:4201

Configuring Nginx (Optional)

If you plan to use the platform locally for your development, you don't need to configure the Nginx, if you are planning to expose it to the internet, then you may need it.

There are two major parts of the platform, one is the core platform and the other is the UI application. Most of our customers keeps the platform within their intranet and expose only their solutions to the outer world.

If your IoT devices are going to use the REST services to push the messages to the platform, then you may need to expose the push API alone.

πŸ“˜

Replace /etc/nginx/sites-enabled/default with the below contents.

proxy_cache_path /tmp/NGINX_cache/ keys_zone=backcache:10m;

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

upstream api_cluster {
    server localhost:18080;
}

upstream micro_api_cluster {
    server localhost:19090;
}

upstream mqttws_cluster {
    server localhost:8083;
}

πŸ“˜

Exposing Boodskap UI

  • Replace the server_name with your domain name
    • Examples
      • server_name platform.your_domain_name
      • server_name your_public_ip_address

Create a file /etc/nginx/sites-enabled/platform.conf with the below contents

#######################

upstream platform_cluster {
    server localhost:4201;
}

server {
    listen 80;
    server_name localhost;
    client_max_body_size 20M;

    location /api {

        proxy_pass http://api_cluster;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-NginX-Proxy true;
        proxy_ssl_session_reuse off;
        proxy_cache backcache;
        proxy_buffer_size          256M;
        proxy_buffers              4 512M;
        proxy_busy_buffers_size    512M;
    }

    location /mservice {

        proxy_pass http://micro_api_cluster;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-NginX-Proxy true;
        proxy_ssl_session_reuse off;
        proxy_cache backcache;
    }

    location /mqtt {

        proxy_pass http://mqttws_cluster;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_redirect  off;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-NginX-Proxy true;
        proxy_ssl_session_reuse off;
        proxy_cache backcache;
    }

    location / {

        proxy_pass http://platform_cluster;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-NginX-Proxy true;
        proxy_ssl_session_reuse off;
        proxy_cache backcache;
        proxy_buffer_size          128k;
        proxy_buffers              4 256k;
        proxy_busy_buffers_size    256k;
    }
}

#######################

πŸ“˜

Exposing REST Push Message API

  • Replace the server_name with your domain name
    • Examples
      • server_name gateway.your_domain_name
      • server_name your_public_ip_address

Create a file /etc/nginx/sites-enabled/push.conf with the below contents

#######################

server {
    listen 80;
    server_name localhost;
    client_max_body_size 20M;
    
     # Use this section if your devices are going to use HTTP REST to push messages
    location /api/push/ {

        proxy_pass http://api_cluster/api/push/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-NginX-Proxy true;
        proxy_ssl_session_reuse off;
        proxy_cache backcache;
        proxy_buffer_size          256M;
        proxy_buffers              4 512M;
        proxy_busy_buffers_size    512M;
    }

    # Use this section if your devices are going to use MQTT Websockets to push messages
    location /mqtt {

        proxy_pass http://mqttws_cluster;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_redirect  off;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-NginX-Proxy true;
        proxy_ssl_session_reuse off;
        proxy_cache backcache;
    }

}

#######################

Updated 4 months ago



Single Machine Installation


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.