puru-soni / kura

Eclipse Kura™ project

Eclipse Kura™

Eclipse Kura, from the maori word for tank/container, is an OSGi-based Application Framework for M2M Service Gateways

Kura aims at offering a Java/OSGi-based container for M2M applications running in service gateways. Kura provides or, when available, aggregates open source implementations for the most common services needed by M2M applications. Kura components are designed as configurable OSGi Declarative Service exposing service API and raising events. While several Kura components are in pure Java, others are invoked through JNI and have a dependency on the Linux operating system.

For more information, see the Eclipse project proposal.

Documentation

• User Documentation: here you'll find information on how to use Eclipse Kura i.e. installation instructions, informations on how to use the web UI and tutorials.
• Developer Documentation: the Eclipse Kura Github Wiki serves as a reference for developers who want to contribute to the Eclipse Kura project and/or develop new add-ons. Here you'll find Eclipse Kura development/release model, guidelines on how to import internal packages, creating new bundles and development environment tips & tricks.
• Docker Containers Documentation: the Eclipse Kura team also provides Docker containers for the project. Informations on how to build and run them are available at the project's Docker Hub page.
• Developer Quickstart Guide: a quick guide on how to setup the development environment and build the project is also provided in this README.

Additionally, we provide two channels for reporting any issue you find with the project

• Github Issues: for bug reporting.
• Github Discussions: for receiving feedback, making new proposals and generally talking about the project.

System Requirements

Eclipse Kura is compatible with Java 8 (Bundle-RequiredExecutionEnvironment: JavaSE-1.8) and OSGi R6.

Development Model

Development on Kura follows a variant of the gitflow model. Development is made on the develop branch. The master branch is not used anymore.

Getting Started

Development for Kura can be done in Eclipse IDE using the Kura Development Environment, in a gateway or in a Docker container.

Development Environment

Supported Development Platforms

The Eclipse Installer based setup works for the main used platforms like Linux, Mac OS and Windows.

Prerequisites

Before installing Kura, you need to have the following programs installed in your system

• JDK 1.8
• Maven 3.5.x

Installing Prerequisites in Mac OS

To install Java 8, download the JDK tar archive from the Adoptium Project Repository.

Once downloaded, copy the tar archive in /Library/Java/JavaVirtualMachines/ and cd into it. Unpack the archive with the following command:

sudo tar -xzf <archive-name>.tar.gz

The tar archive can be deleted afterwards.

Depending on which terminal you are using, edit the profiles (.zshrc, .profile, .bash_profile) to contain:

# Adoptium JDK 8
export JAVA_8_HOME=/Library/Java/JavaVirtualMachines/<archive-name>/Contents/Home
alias java8='export JAVA_HOME=$JAVA_8_HOME'
java8 

Reload the terminal and run java -version to make sure it is installed correctly.

Using Brew you can easily install Maven from the command line:

brew install [email protected]

Run mvn -version to ensure that Maven has been added to the PATH. If Maven cannot be found, try running brew link [email protected] --force or manually add it to your path with:

export PATH="/usr/local/opt/[email protected]/bin:$PATH"

Installing Prerequisites in Linux

For Java

sudo apt install openjdk-8-jdk

For Maven

You can follow the tutorial from the official Maven site. Remember that you need to install the 3.5.x version.

Build Kura

Change to the new directory and clone the Kura repo:

git clone -b develop https://github.com/eclipse/kura.git

Move inside the newly created directory and build the target platform:

mvn -f target-platform/pom.xml clean install

Build the core components:

mvn -f kura/pom.xml clean install

Build the examples (optional):

mvn -f kura/examples/pom.xml clean install

Build the target profiles:

mvn -f kura/distrib/pom.xml clean install -DbuildAll

Note: You can skip tests by adding -Dmaven.test.skip=true in the commands above and you can compile a specific target by specifying the profile (e.g. -Praspberry-pi-armhf).

Build scripts

Alternatively you can use the build scripts available in the root directory.

./build-all.sh

or

./build-menu.sh

and select the profiles you want to build.

Building Eclipse Kura Containers

The kura container build process currently only supports x86 containers. Following the instructions below will build two containers. One based on Alpine Linux kura-alpine-x86_64, and another on Ubi8 kura-ubi8-x86_64.

Build Kura as per our instructions. To build the containers you'll need to change the target of the "Build the target profiles" step like the following:

mvn -f kura/distrib/pom.xml clean install -DbuildAllContainers

Note: this build step requires 'docker' to be a executable command on your system. For Instance, if you are using podman please follow the Emulating Docker Cli Guide before running the command above.

After this command runs, images can be found in your preferred container engine image list.

Eclipse IDE

The simplest way to start developing on Eclipse Kura is to use an Eclipse Installer based setup. A detailed installation and setup guide is available on the official documentation. Here you'll find a brief explaination of the required steps.

To correctly setup the environment, proceed as follows:

• Install a jdk-8 distribution like Eclipse Temurin for your specific CPU architecture and OS.
• Start the Eclipse Installer
• Switch to advanced mode (top right hamburger menu > Advanced Mode)
• Select "Eclipse IDE for Eclipse Committers" and configure the "Product Version" to be the version 2023-03 or newer.
• Select the Eclipse Kura installer from the list. If this is not available, add a new installer from https://raw.githubusercontent.com/eclipse/kura/develop/kura/setups/kura.setup, then check and press the Next button
• Select the "Developer Type":
  • "User": if you want to develop applications or bundles running on Kura, select this option. It will install only the APIs and the examples.
  • "Developer" : if you are a framework developer, select this option. It will download and configure the Eclipse Kura framework.
• Update Eclipse Kura Git repository username and customize further settings if you like (e.g. Root install folder, Installation folder name). To show these options, make sure that the "Show all variables" checkbox is enabled
• Set the JRE 1.8 location value to the installed local jdk-8 VM
• Leave all Bootstrap Tasks selected and press the Finish button
• Accept all the licenses and wait for the installation to finish At first startup Eclipse IDE will checkout the code, perform a full build and configure a few Working Sets
• When the tasks are completed. In the IDE open (double click) Target Platform > Target-Definition > Kura Target Platform Equinox 3.16.0, and press "Set as Target Platform" located at the top right of the window

Now you are ready to develop on Eclipse Kura.

To raise an issue, please report a bug on GitHub issues.

Known Issues

Currently, the emulator web ui is not properly working on Windows so, with your setup, you will be able to build and deploy you applications, but not be able to use the Eclipse IDE based Kura emulator.

The full build of Kura is only supported for Linux and Mac Os based systems.

Currently the maven build on Windows requires to disable the tests and will fail when it tries to create the installers for the target platforms.

Contributing

Contributing to Eclipse Kura is fun and easy! To start contributing you can follow our guide here.

Target Gateways Installers

Eclipse Kura provides pre-built installers for common development boards. Check the following link to download the desired installers.

Docker Image

Eclipse Kura is available also as a Docker container To easily run, use: docker run -d -p 443:443 -t eclipse/kura.