Quick Install

This tutorial describes the steps needed to setup the LoRa Server project including all requirements on a single Ubuntu 16.04 LTS instance. Note that this version of Ubuntu is not required by LoRa Server, but is used in this tutorial as it is the latest Ubuntu LTS version. Please refer to the other install pages for more generic installation instructions.

Assumptions

Many configurations of these packages is possible. Dependent software packages could be installed on any number of remote servers, and the packages themselves could be on their own servers. However, in order to simplify the initial installation, we will assume the following deployment architecture:

Of course, optimizations may need to be made depending on the performance of your systems. You may opt to move the PostgreSQL database to another server. Or you may decide to put your MQTT server on a different system, or even use a different server than the one recommended in this document. These and other installation changes are beyond the scope of this document. However, you should be able to find the information here that would make these changes relatively straight-forward.

Install requirements

Software dependencies for the LoRa Server compoments:

Use the package manager apt to install these dependencies on the Ubuntu 16.04 LTS server:

sudo apt install mosquitto mosquitto-clients redis-server redis-tools postgresql

Mosquitto authentication

Mosquitto, as the main conduit for messaging between the gateways and the LoRa servers and the applications receiving LoRa data, should be secured to prevent third party access to the data. To set up Mosquitto security:

# Create a password file for your mosquitto users, starting with a “root” user.
# The “-c” parameter creates the new password file. The command will prompt for
# a new password for the user.
sudo mosquitto_passwd -c /etc/mosquitto/pwd loraroot

# Add users for the various MQTT protocol users
sudo mosquitto_passwd /etc/mosquitto/pwd loragw
sudo mosquitto_passwd /etc/mosquitto/pwd loraserver
sudo mosquitto_passwd /etc/mosquitto/pwd loraappserver

# Secure the password file
sudo chmod 600 /etc/mosquitto/pwd

Note that further configuration is possible, such as limiting the topics to which the various users can have access. These settings are beyond the scope of this document.

Mosquitto configuration

Add a new local configuration file (this should survive mosquitto upgrades) called /etc/mosquitto/conf.d/local.conf with the following configuration:

Tell mosquitto where the password file is by adding the lines:

allow_anonymous false
password_file /etc/mosquitto/pwd

If you set up SSL/TLS certificates for your server (recommended for production environments) add lines like these pointing to the respective files. Using SSL/TLS is a good idea so that passwords cannot be read as they are sent to Mosquitto for login:

cafile /etc/mosquitto/certs/ca.crt
certfile /etc/mosquitto/certs/hostname.crt
keyfile /etc/mosquitto/certs/hostname.key

After saving this configuration, restart Mosquitto with the new settings:

sudo systemctl restart mosquitto

PostgreSQL databases and users

To enter the command line utility for PostgreSQL:

sudo -u postgres psql

Inside this prompt, execute the following queries to set up the server. It would be wise to change the usernames and passwords. Just remember to use these other values when setting up the configuration for loraserver and lora-app-server. Since these two applications both use the same table to track database upgrades, they must have separate databases.

-- set up the users and the passwords (note that it is important to use single quotes and a semicolon at the end!)
create role loraserver_as with login password 'dbpassword';
create role loraserver_ns with login password 'dbpassword';

-- create the database for the servers
create database loraserver_as with owner loraserver_as;
create database loraserver_ns with owner loraserver_ns;

-- exit psql
\q

Setup LoRa Server software repository

LoRa Server provides a repository that is compatible with the Ubuntu apt package system.

Set up the key for this new repository:

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 1CE2AFD36DBCCA00

Add the repository to the repository list by creating a new file:

sudo echo "deb https://repos.loraserver.io/ubuntu xenial testing" | sudo tee /etc/apt/sources.list.d/loraserver.list

Update the apt system:

sudo apt update

Installing LoRa Gateway Bridge

Note: when you intent to run the LoRa Gateway Bridge only on the gateways itself, you can skip this step. Running LoRa Gateway Brige on your server, without setting up any firewall rules (which is not covered in this guide) allows anybody to send data to your LoRa Server network.

Install the package using apt:

sudo apt install lora-gateway-bridge

Set up your configuration (only the most important settings are addressed here) by changing the configuration file /etc/default/lora-gateway-bridge:

Installing LoRa Server

Install the package using apt:

sudo apt install loraserver

Set up your configuration (only the most important settings are addressed here) by changing the configuration file /etc/default/loraserver:

Start the LoRa Server service:

sudo systemctl start loraserver

Logging for loraserver is accessible via (add -f to follow):

journalctl -u loraserver

Note that you may see errors at this point along the lines of:

INFO[0001] grpc: addrConn.resetTransport failed to create client transport: connection error: desc = "transport: dial tcp 0.0.0.0:8000: getsockopt: connection refused"; Reconnecting to {0.0.0.0:8000 <nil>}

This indicates that LoRa App Server is not yet running. LoRa Server is trying to communicate with LoRa App Server via the gRPC api. Once LoRa App Server is running, this error should stop.

Installing LoRa App Server

Install the package using apt:

sudo apt install lora-app-server

Set up your configuration (only the most important settings are addressed here) by changing the configuration file /etc/default/lora-app-server:

Start the LoRa App Server service:

sudo systemctl start lora-app-server

Logging for LoRa App Server is accessible via (add -f to follow):

journalctl -u lora-app-server

Install LoRa Gateway Bridge on the gateway

It is advised to run LoRa Gateway Bridge on each gateway itself, to enable a secure connection between your gateways and your server.

External dependencies:

As there are many types of gateways available, please refer to the LoRa Gateway Bridge instructions for installing LoRa Gateway Bridge on the server.

Setting up an initial application

In order to receive data from a device / node, that device must be associated with an application. This can be done via the REST interface via some external application, or via the UI that comes with LoRa App Server.

To access the LoRa App Server web-interface, enter the IP address of your server and the port as defined in HTTP_BIND in your browser specifying the https protocol in your browser’s address bar, example: https://localhost:8080.

This will forward to a login screen. A default administrator account is available at installation time with the username of admin and a password of admin (it would be wise to reset the password upon first login). Once logged in, the application dashboard appears. Click the CREATE APPLICATION button, and add an application for your device(s). This only requires an application name and description. Once the application is created, you can click on the title to get a list of the devices associated with the application (none at system installation). Click on the CREATE NODE button to create the node (device). The basic fields that are required are the Node Name, Description, Device EUI, Application EUI, and the Application Key. Other fields may or may not be of interest to your particular setup. Once the device and it application are created, the LoRa Server and LoRa App Server will be able to handle messaging from the device.

Conclusion

At this point you should be able to follow the logs and see no errors. Also, you can user the loraroot account on Mosquitto to watch the message flow:

mosquitto_sub -v -t "#" -u loraroot -P {password} -h localhost -p 1883

Where: