How to create a new module in the platform

Platform extension can be achieved by adding new modules. To do so, there is an available template with the infrastructure of the minimum needed code to develop a module.

Step 1: Download the platform's source code

To download the template, you have to download the platform's source code:

git clone https://github.com/onesaitplatform/onesait-cloud-platform.git

then locate yourself in the master branch:

git checkout master

Step 2: Download onesaitplatform-examples

git clone https://github.com/onesaitplatform/onesait-cloud-platform-examples.git

Having done this, go to the directory /onesait-cloud-platform/sources/examples

Here, you can find several examples of modules in onesaitplatform.

In this folder, find the folder named platform-module-template. You must copy this whole folder to the directory: /onesait-cloud-platform/sources/modules.

This directory contains:

pom.xml (1)
src/
    ModuleTemplateApplication.java (2)
    application.yml (3)
    application-docker.yml (4)
docker/
   Dockerfile (5)

(1) pom.xml is a file Maven need, including information on the project, its configuration, library dependencies, packaging plugins, etc.

This folder can be edited, for instance to name the module:

It contains dependencies with the platform's libraries:

And dependencies with Spring's framework:

And other needed dependencies. In this section, you can add all the libraries you need.

The module's template's whole directory must be copied along with the platform's other modules.

Step 3: compile the new module's and the platform's source code

From the directory sources, you can launch the command mvn clean install that will download the dependencies, compile the sources and generate the module's .class and packages (.jar files). Before that, you need to edit this directory's pom.xml and add your module:

Once mvn clean install has been executed, you should see the following result:

Step 4: run the new module (with and without Eclipse)

(2) The different modules in the platform are written in Java language and use Spring's stack as their development framework, specifically SpringBoot. To do this, the appliaction's main class has been defined with the needed annotations, being the most important ones:

@EnableAutoConfiguration
@ComponentScan

With this two notations in the main class and after importing the module, you can launch it in Eclipse:

Or without Eclipse (if you have previously launched the command mvn clean install from /sources).To do this, you will find two .jar files in the directory /onesait-cloud-platform/sources/modules/platform-module template/target. One of them, ending in -exec.jar, is a file including all the dependencies along with an embedded Tomcat on which your module will be run with the command:

java -jar onesaitplatform-moduletemplate-1.1.0-SNAPSHOT-exec.jar

(3) and (4) Configuration files required by SpringBoot, listening ports, application context, configuration database connection configuration, realtime, Kafka, router, etc.

Step 5: Generate module's Docker image and run the container

The file application-docker.yml contains specific properties that overwrite those in the file application.yml,for the execution of modules within a Docker container.

(5) The Dockerfile is the file including the needed instructions to generate the platform's Docker image. To do this, you need to install previously the Docker engine. To generate the image, you only need to copy the file onesaitplatform-moduletemplate-1.1.0-SNAPSHOT-exec.jar in the module's directory /target to the directory /docker then run the sentence docker build -t onesaitplatform/module:latest .

If you run the command docker images, you can see the image you have just created.

Now you have the generated image in local drive. To run the container, execute the command:

docker run -t -p 19500:19500 onesaitplatform/module:latest

You can access your module from a web browser by listening the port 19500: http://localhost:19500/