supermq

README

SuperMQ

SuperMQ is modern, scalable, secure, open-source, and patent-free cloud platform for messaging and event-driven architecture (EDA) written in Go.

It accepts user and client (device, user, application) connections over various network protocols (i.e. HTTP, MQTT, WebSocket, CoAP), thus making a seamless bridge between them. It is used as the architecture backbone for building complex distributed solutions.

For more details, check out the official documentation. For extra bits and services see our contrib repository.

Features

• Multi-protocol connectivity and bridging (HTTP, MQTT, WebSocket and CoAP; see contrib repository for LoRa and OPC UA)
• Device management and provisioning (Zero Touch provisioning)
• Mutual TLS Authentication (mTLS) using X.509 Certificates
• Fine-grained access control (policies, ABAC/RBAC)
• Message persistence (Timescale and PostgresSQL - see contrib repository for Cassandra, InfluxDB, and MongoDB support)
• Platform logging and instrumentation support (Prometheus and OpenTelemetry)
• Event sourcing
• Container-based deployment using Docker and Kubernetes
• Edge Agent and Export services for remote IoT gateway management and edge computing
• SDK
• CLI
• Small memory footprint and fast execution
• Domain-driven design architecture, high-quality code and test coverage

Prerequisites

The following are needed to run SuperMQ:

• Docker (version 26.0.0)

Developing SuperMQ will also require:

• Go (version 1.21)
• Protobuf (version 25.1)

Install

Once the prerequisites are installed, execute the following commands from the project's root:

docker compose -f docker/docker-compose.yml --env-file docker/.env -p git_github_com_absmach_supermq_git_  up

This will bring up the SuperMQ docker services and interconnect them. This command can also be executed using the project's included Makefile:

make run

If you want to run services from specific release checkout code from github and make sure that SMQ_RELEASE_TAG in .env is being set to match the release version

git checkout tags/<release_number> -b <release_number>
# e.g. `git checkout tags/0.13.0 -b 0.13.0`

Check that .env file contains:

SMQ_RELEASE_TAG=<release_number>

docker-compose should be used for development and testing deployments. For production we suggest using Kubernetes.

Usage

The quickest way to start using SuperMQ is via the CLI. The latest version can be downloaded from the official releases page.

It can also be built and used from the project's root directory:

make cli
./build/cli version

Additional details on using the CLI can be found in the CLI documentation.

Documentation

Official documentation is hosted at SuperMQ official docs page. Documentation is auto-generated, checkout the instructions on official docs repository:

If you spot an error or a need for corrections, please let us know - or even better: send us a PR.

Authors

Main architect and BDFL of SuperMQ project is @drasko.

Additionally, @nmarcetic and @janko-isidorovic assured overall architecture and design, while @manuio and @darkodraskovic helped with crafting initial implementation and continuously worked on the project evolutions.

Besides them, SuperMQ is constantly improved and actively developed by @anovakovic01, @dusanb94, @srados, @gsaleh, @blokovi, @chombium, @mteodor, @rodneyosodo and a large set of contributors.

Maintainers are listed in MAINTAINERS file.

The SuperMQ team would like to give special thanks to @mijicd for his monumental work on designing and implementing a highly improved and optimized version of the platform, and @malidukica for his effort on implementing the initial user interface.

Professional Support

There are many companies offering professional support for the SuperMQ system.

If you need this kind of support, best is to reach out to @drasko directly, and he will point you out to the best-matching support team.

Contributing

Thank you for your interest in SuperMQ and the desire to contribute!

1. Take a look at our open issues. The good-first-issue label is specifically for issues that are great for getting started.
2. Checkout the contribution guide to learn more about our style and conventions.
3. Make your changes compatible to our workflow.

Also, explore our contrib repository for extra services such as Cassandra, InfluxDB, MongoDB readers and writers, LoRa, OPC UA support, Digital Twins, and more. If you have a contribution that is not a good fit for the core monorepo (it's specific to your use case, it's an additional feature or a new service, it's optional or an add-on), this is a great place to submit the pull request.

We're Hiring

You like SuperMQ and you would like to make it your day job? We're always looking for talented engineers interested in open-source, IoT and distributed systems. If you recognize yourself, reach out to @drasko - he will contact you back.

The best way to grab our attention is, of course, by sending PRs 😎.

Community

• Google group
• Gitter
• Twitter

License

Apache-2.0

Data Collection for SuperMQ

SuperMQ is committed to continuously improving its services and ensuring a seamless experience for its users. To achieve this, we collect certain data from your deployments. Rest assured, this data is collected solely for the purpose of enhancing SuperMQ and is not used with any malicious intent. The deployment summary can be found on our website.

The collected data includes:

• IP Address - Used for approximate location information on deployments.
• Services Used - To understand which features are popular and prioritize future developments.
• Last Seen Time - To ensure the stability and availability of SuperMQ.
• SuperMQ Version - To track the software version and deliver relevant updates.

We take your privacy and data security seriously. All data collected is handled in accordance with our stringent privacy policies and industry best practices.

Data collection is on by default and can be disabled by setting the env variable: SMQ_SEND_TELEMETRY=false

By utilizing SuperMQ, you actively contribute to its improvement. Together, we can build a more robust and efficient platform. Thank you for your trust in SuperMQ!

Documentation

Overview

Package supermq acts as an umbrella package containing multiple different microservices and defines all shared domain concepts. For detailed documentation of the platform, please visit https://docs.supermq.abstractmachines.fr.

Index

• Variables
• func Health(service, instanceID string) http.HandlerFunc
• type HealthInfo
• type IDProvider
• type Response

Variables

var (
	// Version represents the last service git tag in git history.
	// It's meant to be set using go build ldflags:
	// -ldflags "-X 'github.com/absmach/supermq.Version=0.0.0'".
	Version = "0.0.0"
	// Commit represents the service git commit hash.
	// It's meant to be set using go build ldflags:
	// -ldflags "-X 'github.com/absmach/supermq.Commit=ffffffff'".
	Commit = "ffffffff"
	// BuildTime represetns the service build time.
	// It's meant to be set using go build ldflags:
	// -ldflags "-X 'github.com/absmach/supermq.BuildTime=1970-01-01_00:00:00'".
	BuildTime = "1970-01-01_00:00:00"
)

Functions

func Health

func Health(service, instanceID string) http.HandlerFunc

Health exposes an HTTP handler for retrieving service health.

Types

type HealthInfo

type HealthInfo struct {
	// Status contains service status.
	Status string `json:"status"`

	// Version contains current service version.
	Version string `json:"version"`

	// Commit represents the git hash commit.
	Commit string `json:"commit"`

	// Description contains service description.
	Description string `json:"description"`

	// BuildTime contains service build time.
	BuildTime string `json:"build_time"`

	// InstanceID contains the ID of the current service instance
	InstanceID string `json:"instance_id"`
}

HealthInfo contains version endpoint response.

type IDProvider

type IDProvider interface {
	// ID generates the unique identifier.
	ID() (string, error)
}

IDProvider specifies an API for generating unique identifiers.

type Response

type Response interface {
	// Code returns HTTP response code.
	Code() int

	// Headers returns map of HTTP headers with their values.
	Headers() map[string]string

	// Empty indicates if HTTP response has content.
	Empty() bool
}

Response contains HTTP response specific methods.