mainflux

README

Mainflux

Mainflux is modern, scalable, secure, open-source, and patent-free IoT cloud platform written in Go.

It accepts user and thing (sensor, actuator, application) connections over various network protocols (i.e. HTTP, MQTT, WebSocket, CoAP), thus making a seamless bridge between them. It is used as the IoT middleware for building complex IoT solutions.

For more details, check out the official documentation.

Features

• Multi-protocol connectivity and bridging (HTTP, MQTT, WebSocket and CoAP)
• Device management and provisioning (Zero Touch provisioning)
• Mutual TLS Authentication (mTLS) using X.509 Certificates
• Fine-grained access control (policies, ABAC/RBAC)
• Message persistence (Cassandra, InfluxDB, MongoDB and PostgresSQL)
• Platform logging and instrumentation support (Grafana, Prometheus and OpenTracing)
• 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 Mainflux:

• Docker (version 20.10)
• Docker compose (version 1.29)

Developing Mainflux will also require:

• Go (version 1.13.3)
• Protobuf (version 3.6.1)

Install

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

docker-compose -f docker/docker-compose.yml up

This will bring up the Mainflux 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 MF_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:

MF_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 Mainflux 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/mainfluxlabs-cli version

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

Documentation

Official documentation is hosted at Mainflux 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 Mainflux 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, Mainflux is constantly improved and actively developed by @anovakovic01, @dusanb94, @srados, @gsaleh, @blokovi, @chombium, @mteodor and a large set of contributors.

Maintainers are listed in MAINTAINERS file.

The Mainflux 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 Mainflux 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 Mainflux 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.

License

Apache-2.0

Documentation

Index

• Variables
• func Env(key, fallback string) string
• func Health(service string) http.HandlerFunc
• func LoadEnvFile(envfilepath string) error
• type HealthInfo

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/MainfluxLabs/mainflux.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/MainfluxLabs/mainflux.Commit=ffffffff'"
	Commit = "ffffffff"
	// BuildTime represetns the service build time.
	// It's meant to be set using go build ldflags:
	// -ldflags "-X 'github.com/MainfluxLabs/mainflux.BuildTime=1970-01-01_00:00:00'"
	BuildTime = "1970-01-01_00:00:00"
)

Functions

func Env

func Env(key, fallback string) string

Env reads specified environment variable. If no value has been found, fallback is returned.

func Health

func Health(service string) http.HandlerFunc

Health exposes an HTTP handler for retrieving service health.

func LoadEnvFile

func LoadEnvFile(envfilepath string) error

LoadEnvFile loads environment variables defined in an .env formatted file.

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"`
}

HealthInfo contains version endpoint response.