Skip to content

Getting started

Jump to bottom
ogumennyi edited this page May 25, 2017 · 12 revisions

Running DeviceHive Server as a standalone application

Prerequisites

In order to use DeviceHive framework you must have the following components installed and configured:

Running Apache Kafka

Start Zookeeper and Apache Kafka brokers as explained at official documentation (http://kafka.apache.org/documentation.html#quickstart).

If your Kafka and Zookeeper are installed on different machines, or on non-default ports, you will have to update the server configuration. To do so, open

devicehive-backend/src/main/resources/application.properties

devicehive-frontend/src/main/resources/application.properties

In all 3 files, find the zookeeper.connect (zookeeper's contact point) and bootstrap.servers (list of Kafka brokers) properties and update them to the correct hostnames and ports.

Build packages

Download source code from GitHub using "Download ZIP" button. It should always point to recent stable or beta release, but you always can get any other tag or branch. It also can be done using one of Git version control client or git command line tool. If you prefer git, clone project using command

git clone https://github.com/devicehive/devicehive-java-server.git

After that you can switch to the tag or branch you need. The list of all available releases can be found at https://github.com/devicehive/devicehive-java-server/releases Execute following command from ${devicehive-java-server-directory}.

mvn clean package

If there are no errors, compilation and packaging are completed and you can go to the next step.

Starting database

Download and install PostgreSQL (see https://wiki.postgresql.org/wiki/Detailed_installation_guides) By default, DH expects a user with the username postgres and the password 12345. You can change this in the DH configuration file (devicehive-rdbms-dao/src/main/resources/application-persistence.properties).

Create database with the name devicehive with the postgres user. This user should be the owner of the database.

Database schema will be initialized on application startup.

Setup environment variables

The only variable that needs to be setup at the moment is a JWT secret. Create a variable called "JWT_SECRET" and set there a value, that should meet your security risks. Recommended key length is 128 bits, or more.

At the system start up, if JWT secret was set, it would be saved in the DB, in other case, it would be auto-generated and saved in the DB as well. Each time system starts, it checks the environment variable first, then checks the value from DB, and after all generates a new key. So, unless the DB would not be recreated, already generated tokens would be valid. But still, using a system variable is a highly recommended option.

Running application

To start the application, you have to start the backend and the frontend. To do this, first run following command:

java -jar ${devicehive-java-server-directory}/devicehive-backend/target/devicehive-backend-<version>-boot.jar

Wait for the application to start, then run:

java -jar ${devicehive-java-server-directory}/devicehive-frontend/target/devicehive-frontend-<version>-boot.jar

This will start embedded undertow application server on default port 8080 and deploy DeviceHive application.

Running DeviceHive Server using Docker

We have published a DeviceHive docker container so you can utilize docker's virtualization features with DeviceHive. Check out DeviceHive on Docker Hub with the instructions on how to use it. You can check dockerfile implementation as well as the script for setting up a new instance running under nginx on DeviceHive Docker

Clone this wiki locally