Contribute Guide

We are constantly looking for a feedback from our community on how to improve JIoT. If you have an idea or you have some new features in mind, please open an issue at JIoT Gitlab issue page. Please make sure that the same ticket is not already opened in the issues list (or something very similar).

Before you start any implementation please wait from the JIoT team to comment on your ticket. We’ll try to get back to you ASAP.

Required Tools

To build and run JIoT instance make sure that you have Java and Maven installed onto your system.

Please refer to Building from sources section where Java and Maven install processes are described.

Fork and build JIoT repository.

Once you have completed installation of required tools please fork official JIoT repository.

Now you can clone source code of the forked project.

NOTE: We will refer later to the folder where you have cloned repository as ${JT_WORK_DIR}.

If are building on Windows for the first time, you may need to run these commands to ensure the required npm dependencies are available:

npm install -g cross-env 
npm install -g webpack 

Before importing the project into the IDE please build it using Maven tool from the root folder:

cd ${JT_WORK_DIR}
mvn clean install -DskipTests

A build will generate all the protobuf files in the application module that are needed for the correct compilation in your IDE.

Next, import the project into your favorite IDE as Maven project. See separate instructions for IDEA and Eclipse.

NOTE: If you are using Eclipse, after the maven project is imported to the IDE, We recommend you to disable Maven Project builder on ui project. This will improve the Eclipse performance a lot, because it will avoid Eclipse Maven builder from digging in node_modules directory (which is unnecessary and only causes Eclipse to hang). To do this, right-click on ui project, go to Properties -> Builders, and then uncheck the Maven Project Builder checkbox and then click Ok.

Database

By default, JIoT uses embedded HSQLDB instance which is very convenient for evaluation or development purposes.

Alternatively, you can configure your platform to use either scalable Cassandra DB cluster or various SQL databases. If you prefer to use an SQL database, we recommend PostgreSQL.

Optional: SQL Database: PosgreSQL

NOTE: This is an optional step. It is required only for production usage. You can use embedded HSQLDB for platform evaluation or development

Please use this link for the PostgreSQL installation instructions.

Once PostgreSQL is installed you may want to create a new user or set the password for the main user.

When it’s done, connect to the database and create jiot DB:

psql -U postgres -d postgres -h 127.0.0.1 -W

CREATE DATABASE jiot;
\q

Optional: NoSQL Database: Cassandra

Please refer to appropriate section where you find instructions on how to install cassandra:

• Cassandra installation on Linux

• Cassandra installation on Windows

Optional: Configure JIoT to use external database

NOTE: This is an optional step. It is required only for production usage. You can use embedded HSQLDB for platform evaluation or development

Edit JIoT configuration file:

/application/scr/main/resources/jiot.yml

Comment ‘# HSQLDB DAO Configuration’ block.

# HSQLDB DAO Configuration
#spring:
#  data:
#    jpa:
#      repositories:
#        enabled: "true"
#  jpa:
#    hibernate:
#      ddl-auto: "validate"
#    database-platform: "org.hibernate.dialect.HSQLDialect"
#  datasource:
#    driverClassName: "${SPRING_DRIVER_CLASS_NAME:org.hsqldb.jdbc.JDBCDriver}"
#    url: "${SPRING_DATASOURCE_URL:jdbc:hsqldb:file:${SQL_DATA_FOLDER:/tmp}/jiotDb;sql.enforce_size=false}"
#    username: "${SPRING_DATASOURCE_USERNAME:sa}"
#    password: "${SPRING_DATASOURCE_PASSWORD:}"

For PostgreSQL:

Uncomment ‘# PostgreSQL DAO Configuration’ block. Be sure to update the postgres databases username and password in the bottom two lines of the block (here, as shown, they are both “postgres”).

# PostgreSQL DAO Configuration
spring:
  data:
    jpa:
      repositories:
        enabled: "true"
  jpa:
    hibernate:
      ddl-auto: "validate"
    database-platform: "org.hibernate.dialect.PostgreSQLDialect"
  datasource:
    driverClassName: "${SPRING_DRIVER_CLASS_NAME:org.postgresql.Driver}"
    url: "${SPRING_DATASOURCE_URL:jdbc:postgresql://localhost:5432/jiot}"
    username: "${SPRING_DATASOURCE_USERNAME:postgres}"
    password: "${SPRING_DATASOURCE_PASSWORD:postgres}"

For Cassandra DB:

Locate and set database type configuration parameter to ‘cassandra’.

database:
  type: "${DATABASE_TYPE:cassandra}" # cassandra OR sql

NOTE: If your Cassandra server is installed on the remote machine or it is bind to custom interface/port, you need to specify it in jiot.yml as well. Please, tefer to the configuration guide for the detailed description of jiot.yml file and what properties are used for cassandra connection configuration.

After the jiot.yml file was updated, please rebuild the application module so that the updated jiot.yml gets populated to the target directory:

cd ${TB_WORK_DIR}/application
mvn clean install -DskipTests

Create Database schema and populate demo data

In order to create the database tables, run the following:

On Linux:

cd ${TB_WORK_DIR}/application/target/bin/install
chmod +x install_dev_db.sh
./install_dev_db.sh

On Windows:

cd %TB_WORK_DIR%\application\target\windows
install_dev_db.bat

Running development environment

Running UI container in hot redeploy mode.

By default, JIoT UI is served at 8080 port. However, you may want to run UI in the hot redeploy mode.

NOTE: This step is optional. It is required only if you are going to do changes to UI.

To start UI container in hot redeploy mode you will need to install node.js first. Once node.js is installed you can start container by executing next command:

cd ${JT_WORK_DIR}/ui
mvn clean install -P npm-start

This will launch a special server that will listen on 3000 port. All REST API and websocket requests will be forwarded to 8080 port.

Running server-side container

To start server-side container you can use couple options.

As a first option, you can run the main method of org.jiot.server.JIoTServerApplication class that is located in application module from your IDE.

As a second option, you can start the server from command line as a regular Spring boot application:

cd ${JT_WORK_DIR}
java -jar application/target/jiot-${VERSION}-boot.jar

Dry Run

Navigate to http://localhost:3000/ or http://localhost:8080/ and login into JIoT using demo data credentials:

• login [e-mail]

• password jiot

Make sure that you are able to login and everything has started correctly.

Code changes

Now you are ready to start to do some changes to the codebase. Update server-side or UI code. Verify that changes that you have done meet your requirements and expectations from the user perspective.

Verify build

Before you commit your changes to the remote repository build it locally with tests run using Maven:

mvn clean install

Make sure that build is fine and all the tests are successful.

Push changes to your fork

When you are done with code changes commit and push them to your forked repository with some meaningful comment:

git commit -m 'Some meaningful comment'
git push origin master

Create pull request

Please create pull request into the master branch by default (the additional branch name will be provided during the initial stage of gitlab issue discussion if needed).

If there are some conflicts because new stuff has arrived into JIoT master branch before your commit, please resolve those conflicts to continue.

Sign up contribution license agreement (CLA) and verify that remote build has been successful. The CLA is signed atomatically using the github CLA bot.