• Stars
    star
    218
  • Rank 175,514 (Top 4 %)
  • Language
    Java
  • License
    Eclipse Public Li...
  • Created over 7 years ago
  • Updated 29 days ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Eclipse Kapuaâ„¢ logo

Eclipse Kapuaâ„¢

GitHub Release GitHub

GitHub Issues GitHub Pull Requests GitHub Contributors GitHub Forks

Gitter

GitHub Actions CI
Jenkins

Eclipse Kapuaâ„¢ is a modular platform providing the services required to manage IoT gateways and smart edge devices. Kapua provides a core integration framework and an initial set of core IoT services including a device registry, device management services, messaging services, data management, and application enablement.

Quick Start Guide

Running an Eclipse Kapuaâ„¢ demo instance on your local machine is a simple task.

Eclipse Kapuaâ„¢ runs as distributed application that exposes three basic services:

  • The Messaging Service
  • The RESTful API
  • The Web Administration Console

Two more backend services are required that implement the data tier:

  • The Event Bus Service
  • The SQL database
  • The NoSQL datastore

Eclipse Kapuaâ„¢ can be deployed in a variety of modes. A practical way for running a local demo is through Docker containers.

Requirements

Before starting, check that your environment has the following prerequisites:

  • 64 bit architecture
  • Java VM Version 8
  • Java VM Version 11
  • Docker Version 1.2+
  • Swagger CLI 4+ (Installed via NPM or separately)
  • Node 16+
  • Internet Access (needed to download the artifacts)

Demo Setup

The team maintains some docker images in a Docker Hub repository at Kapua Repository. Check the repo to view the list of available images, if you haven't found one fitting your needs you may create your own. Please refer to the paragraph More deployment info to find more about creating your own images and/or alternative demo deployment scenarios.


Note: the Docker Hub repository mentioned above is not the official project repository from Eclipse Foundation.


Suppose the target is the current snapshot 2.1.0-SNAPSHOT.

  • Clone Eclipse Kapuaâ„¢ into a local directory
  • Open an OS shell and move to Kapua project root directory
  • Start Docker runtime

The Kapua repository mentioned above hosts only images of released versions. It is possible to test different versions of Kapua doing a checkout into the release branches (for example, "release-1.6.x") and to the tagged commits to select the specific version (for example, the commit tagged as "1.6.7"). Doing so, it is assured that the following step will pull proper images from the Docker Hub. If, on the other hand, your target is a SNAPSHOT version (for example, the 2.1.0-SNAPSHOT), a local build is required in order to create the docker images and proceed to the next step. Instructions for building can be found in the building.md file under the path docs/developer-guide. Assuming that your interest is to deploy a release before 2.0.0 and that you want to pull images from the Docker Hub, it is important to set now the IMAGE_VERSION environment variable with a value equal to the target version. For example, in the case of the 1.6.7

export IMAGE_VERSION=1.6.7
  • Start Kapua:

On Linux/MacOS:

    ./deployment/docker/unix/docker-deploy.sh

On Windows (PowerShell):

    ./deployment/docker/win/docker-deploy.ps1

The command starts all the Kapua containers using Docker Compose.

You can check if the containers are running by typing the following command:

    docker ps -as

Docker will list the containers currently running.

To stop Kapua, run

On Linux/MacOS:

    ./deployment/docker/unix/docker-undeploy.sh

On Windows (PowerShell):

    ./deployment/docker/win/docker-undeploy.ps1

Access

Once the containers are running, the Kapua services can be accessed. Eclipse Kapuaâ„¢ is a multi tenant system. The demo installation comes with one default tenant, called kapua-sys, which is also the root tenant. In Eclipse Kapuaâ„¢ a tenant is commonly referred to as an account.

The console

The administration console is available at http://localhost:8080/. Copy paste the URL above to a Web browser, as the login screen appears, type the following credentials:

  • Username: kapua-sys
  • Password: kapua-password

Press Login button and start working with the console.

Note: If you are using Docker on Windows the hostname will most likely not be localhost but the IP address of your docker instance.

RESTful APIs

The documentation of RESTful API is available at http://localhost:8081/doc/ while the mount points are available at http://localhost:8081/v1/ .

The documentation is available through Swagger UI which greatly helps testing and exploring the exposed services.

In order to get access a REST resource through an API, an authentication token is needed. Fortunately the token can be easily obtained by executing the authentication API. There are several ways to invoke the API, an easy one is by using the Swagger UI:

  • Open the URL http://localhost:8081/doc/
  • Select item Authentication
  • Select item /authentication/user
  • Using the test feature run 'POST /authentication/user' by specifying the following body:
{
  "password": [
    "kapua-password"
  ],
  "username": "kapua-sys"
}

Note: as an alternative to the previous, if curl is available on your machine, execute the following from the shell:

curl -X POST  'http://localhost:8081/v1/authentication/user' --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
  "password": [
    "kapua-password"
  ],
  "username": "kapua-sys"
}'

The system will return a JSON object.

  • Copy the value of the field tokenId
  • Paste the value in the box labelled api_key at the top of the web page

Swagger will automatically add the authentication token to each subsequent request done using the Swagger UI. You're ready to try executing the documented APIs.

Note: If you are using Docker on Windows the hostname will most likely not be localhost but the IP address of your docker instance.

The Broker

The broker container exposes an Mqtt end point at tcp://localhost:1883/. The broker can be accessed through either Eclipse Kuraâ„¢ or a plain Mqtt client like, for example, Eclipse Pahoâ„¢.

In order for a client to establish a Mqtt connection with the broker, a client must provide a valid identity. The kapua-sys account provides the user named kapua-broker which has been pre-seeded and profiled for the purpose.

The credentials for the user kapua-broker are the following:

  • Username: kapua-broker
  • Password: kapua-password

Note: do not use the user kapua-sys to establish Mqtt connections.

Note: If you are using Docker on Windows the hostname will most likely not be localhost but the IP address of your docker instance.

Simulation

Kapua comes with a framework that you can use to simulate Kura gateways. It can be used to test your Kapua deployments easily. See Simulator documentation for more info.

More deployment info

Installing and running a demo using Docker is easy, but it's not the only way. There are other scenarios that the users may be interested in. We provide advanced setup scenarios in the following guides:

They will provide more advanced deployment scenarios.

User & Developer guides

Contributing

If you're interested to get involved in IoT and Eclipse Kapuaâ„¢ project, join the community and give your contribution to the project, please read how to contribute to Eclipse Kapuaâ„¢.

Community

Acknowledgments

Thanks to YourKit for providing us an open source license of YourKit Java Profiler!

YourKit supports open source projects with innovative and intelligent tools for monitoring and profiling Java and .NET applications. YourKit is the creator of YourKit Java Profiler, YourKit .NET Profiler, and YourKit YouMonitor.

More Repositories

1

mosquitto

Eclipse Mosquitto - An open source MQTT broker
C
7,649
star
2

che

Kubernetes based Cloud Development Environments for Enterprise Teams
TypeScript
6,868
star
3

jetty.project

Eclipse Jetty® - Web Container & Clients - supports HTTP/2, HTTP/1.1, HTTP/1.0, websocket, servlets, and more
Java
3,655
star
4

paho.mqtt.android

MQTT Android
Java
2,708
star
5

paho.mqtt.golang

Go
2,381
star
6

eclipse-collections

Eclipse Collections is a collections framework for Java with optimized data structures and a rich, functional and fluent API.
Java
2,283
star
7

paho.mqtt.java

Eclipse Paho Java MQTT client library. Paho is an Eclipse IoT project.
Java
2,000
star
8

paho.mqtt.python

paho.mqtt.python
Python
1,946
star
9

sumo

Eclipse SUMO is an open source, highly portable, microscopic and continuous traffic simulation package designed to handle large networks. It allows for intermodal simulation including pedestrians and comes with a large set of tools for scenario creation.
1,902
star
10

paho.mqtt.c

An Eclipse Paho C client library for MQTT for Windows, Linux and MacOS. API documentation: https://eclipse.github.io/paho.mqtt.c/
C
1,736
star
11

eclipse.jdt.ls

Java language server
Java
1,410
star
12

mraa

Linux Library for low speed IO Communication in C with bindings for C++, Python, Node.js & Java. Supports generic io platforms, as well as Intel Edison, Intel Joule, Raspberry Pi and many more.
C
1,349
star
13

paho.mqtt.embedded-c

Paho MQTT C client library for embedded systems. Paho is an Eclipse IoT project (https://iot.eclipse.org/)
C
1,271
star
14

paho.mqtt.javascript

paho.mqtt.javascript
JavaScript
1,115
star
15

openvsx

An open-source registry for VS Code extensions
Java
1,059
star
16

milo

Eclipse Miloâ„¢ - an open source implementation of OPC UA (IEC 62541).
Java
976
star
17

omr

Eclipse OMRâ„¢ Cross platform components for building reliable, high performance language runtimes
C++
917
star
18

paho.mqtt.cpp

C++
875
star
19

xtext

Eclipse Xtextâ„¢ is a language development framework
Java
715
star
20

upm

UPM is a high level repository that provides software drivers for a wide variety of commonly used sensors and actuators. These software drivers interact with the underlying hardware platform through calls to MRAA APIs.
C++
651
star
21

microprofile

Repository for important documentation - the index to the project / community
Java
635
star
22

californium

CoAP/DTLS Java Implementation
Java
620
star
23

leshan

Java Library for LWM2M
Java
614
star
24

paho.mqtt-spy

mqtt-spy is an open source desktop & command line utility intended to help you with monitoring activity on MQTT topics
Java
605
star
25

jkube

Build and Deploy java applications on Kubernetes
Java
593
star
26

steady

Analyses your Java applications for open-source dependencies with known vulnerabilities, using both static analysis and testing to determine code context and usage for greater accuracy. https://eclipse.github.io/steady/
Java
516
star
27

sprotty

A diagramming framework for the web
TypeScript
514
star
28

buildship

The Eclipse Plug-ins for Gradle project.
Java
507
star
29

paho.mqtt.m2mqtt

C#
495
star
30

lsp4j

A Java implementation of the language server protocol intended to be consumed by tools and language servers implemented in Java.
Java
473
star
31

kura

Eclipse Kuraâ„¢ project
Java
469
star
32

wakaama

Eclipse Wakaama is a C implementation of the Open Mobile Alliance's LightWeight M2M protocol (LWM2M).
C
465
star
33

streamsheets

An open-source tool for processing stream data using a spreadsheet-like interface.
JavaScript
441
star
34

paho.mqtt.rust

paho.mqtt.rust
Rust
422
star
35

jifa

🔬 Online Heap Dump, GC Log & Thread Dump Analyzer. Make troubleshooting easy.
Java
421
star
36

hawkbit

Eclipse hawkBitâ„¢
Java
416
star
37

eclipse-collections-kata

Eclipse Collections Katas
Java
411
star
38

hono

Eclipse Honoâ„¢ Project
Java
378
star
39

repairnator

Software development bots for Github. Join the bot revolution! 🌟🤖🌟💞
Java
370
star
40

ponte

Ponte Project
JavaScript
360
star
41

birt

Eclipse BIRTâ„¢ The open source reporting and data visualization project.
Java
355
star
42

rdf4j

Eclipse RDF4J: scalable RDF for Java
Java
323
star
43

paho.mqtt-sn.embedded-c

Paho C MQTT-SN gateway and libraries for embedded systems. Paho is an Eclipse IoT project.
C++
305
star
44

paho.golang

Go libraries
Go
269
star
45

lemminx

XML Language Server
Java
242
star
46

vorto

Vorto Project
Java
221
star
47

elk

Eclipse Layout Kernel - Automatic layout for Java applications.
Java
211
star
48

jnosql

Eclipse JNoSQL is a framework which has the goal to help Java developers to create Jakarta EE applications with NoSQL.
Java
210
star
49

corrosion

Eclipse Corrosion - Rust edition in Eclipse IDE
Java
199
star
50

capella

Open Source Solution for Model-Based Systems Engineering
Java
197
star
51

dirigible

Eclipse Dirigibleâ„¢ Project
JavaScript
196
star
52

tahu

Eclipse Tahu addresses the existence of legacy SCADA/DCS/ICS protocols and infrastructures and provides a much-needed definition of how best to apply MQTT into these existing industrial operational environments.
Java
196
star
53

microprofile-config

MicroProfile Configuration Feature
Java
182
star
54

wildwebdeveloper

Simple and productive Web Development Tools in the Eclipse IDE
Java
181
star
55

pdt

PHP Development Tools project (PDT)
PHP
178
star
56

org.aspectj

Java
172
star
57

xacc

XACC - eXtreme-scale Accelerator programming framework
C++
137
star
58

thingweb.node-wot

thingweb.node-wot
TypeScript
130
star
59

microprofile-rest-client

MicroProfile Rest Client
Java
124
star
60

tycho

Tycho project repository (tycho)
Java
119
star
61

microprofile-conference

Microprofile.io Demo Code - Web Services Conference Application
Java
117
star
62

microprofile-fault-tolerance

microprofile fault tolerance
Java
115
star
63

microprofile-samples

Micro Profile Samples
Java
115
star
64

xtext-core

xtext-core
Java
114
star
65

microprofile-open-api

Microprofile open api
Java
112
star
66

gef

Eclipse GEFâ„¢
Java
111
star
67

jbom

Java
104
star
68

paho.mqtt.testing

An Eclipse Paho project - a Python broker for testing
Python
104
star
69

xtext-xtend

xtext-xtend
Java
100
star
70

transformer

Eclipse Transformer provides tools and runtime components that transform Java binaries, such as individual class files and complete JARs and WARs, mapping changes to Java packages, type names, and related resource names.
Java
97
star
71

microprofile-health

microprofile-health
Java
95
star
72

microprofile-metrics

microprofile-metrics
Java
94
star
73

microprofile-graphql

microprofile-graphql
Java
93
star
74

sw360

SW360 project
Java
92
star
75

microprofile-jwt-auth

Java
92
star
76

tinydtls

Eclipse tinydtls
C
92
star
77

microprofile-lra

microprofile-lra
Java
90
star
78

mosaic

Eclipse MOSAIC is a Multi-Domain and Multi-Scale Simulation Framework for Automated and Connected Mobility Scenarios.
Java
81
star
79

kuksa.val

kuksa.val
Rust
80
star
80

nebula

Nebula Project
Java
79
star
81

microprofile-reactive-streams-operators

Microprofile project
Java
75
star
82

mosquitto.rsmb

Mosquitto rsmb
C
75
star
83

microprofile-starter

MicroProfile project generator source code
Java
68
star
84

aCute

Eclipse aCute - C# edition in Eclipse IDE
Java
65
star
85

ditto-examples

Eclipse Dittoâ„¢: Digital Twin framework - Examples
Java
63
star
86

tm4e

TextMate support in Eclipse IDE
Java
60
star
87

californium.tools

Californium project
Java
59
star
88

microprofile-opentracing

microprofile-opentracing
Java
57
star
89

microprofile-reactive-messaging

Java
57
star
90

eclemma

🌘 Java Code Coverage for Eclipse IDE
Java
57
star
91

texlipse

Eclipse Texlipse
Java
56
star
92

dartboard

Dart Plugin for Eclipse
Java
55
star
93

jnosql-databases

This project contains Eclipse JNoSQL databases
Java
54
star
94

windowbuilder

Eclipse Windowbuilder
Java
54
star
95

lsp4e

Language Server Protocol support in Eclipse IDE
Java
53
star
96

mita

mita
Xtend
53
star
97

xtext-eclipse

xtext-eclipse
Java
49
star
98

che-che4z-lsp-for-cobol

COBOL Language Support provides autocomplete, highlighting and diagnostics for COBOL code and copybooks
COBOL
46
star
99

packages

IoT Packages project
Smarty
44
star
100

winery

Eclipse Winery project
Java
44
star