> For the complete documentation index, see [llms.txt](https://astian.gitbook.io/jiot/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://astian.gitbook.io/jiot/contribute-guide.md).

# 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**](https://gitlab.com/jiot/jiot/issues). 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**](https://thingsboard.io/docs/user-guide/install/building-from-source/#java) and [**Maven**](https://thingsboard.io/docs/user-guide/install/building-from-source/#maven) install processes are described.

### Fork and build JIoT repository.

Once you have completed installation of required tools please fork official [**JIoT repository**](https://gitlab.com/jiot/jiot).

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**](https://www.jetbrains.com/help/idea/2016.3/importing-project-from-maven-model.html) and [**Eclipse**](http://javapapers.com/java/import-maven-project-into-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](https://wiki.postgresql.org/wiki/Detailed_installation_guides) 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**](https://thingsboard.io/docs/user-guide/install/linux/#cassandra)
* [Cassandra installation on **Windows**](https://thingsboard.io/docs/user-guide/install/windows/#cassandra)

### 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* **<jiot@astian.org>**
* *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.