README
¶
Magistrala
A Modern IoT Platform Built on SuperMQ
Scalable • Secure • Open-Source
Guide | Contributing | Website | Chat
Made with ❤️ by Abstract Machines
Introduction 🌍
Magistrala is a cutting-edge, open-source IoT cloud platform built on top of SuperMQ. It serves as a robust middleware solution for building complex IoT applications. With Magistrala, you can connect and manage IoT devices seamlessly using multi-protocol support, all while ensuring security and scalability.
Key Benefits:
- Unified IoT Management: Connect sensors, actuators, and applications over various network protocols.
- Scalability and Performance: Designed to handle enterprise-grade IoT deployments.
- Secure by Design: Features such as mutual TLS authentication and fine-grained access control.
- Open-Source Freedom: Patent-free, community-driven, and designed for extensibility.
✨ Features
- 🏢 Multi-Tenancy: Support for managing multiple independent domains seamlessly.
- 👥 Multi-User Platform: Unlimited organizational hierarchies and user roles for streamlined collaboration.
- 🌐 Multi-Protocol Connectivity: HTTP, MQTT, WebSocket, CoAP, and more (see contrib repository for LoRa and OPC UA).
- 💻 Device Management and Provisioning: Including Zero-Touch provisioning for seamless device onboarding.
- 🛡️ Mutual TLS Authentication (mTLS): Secure communication using X.509 certificates.
- 📜 Fine-Grained Access Control: Support for ABAC and RBAC policies.
- 💾 Message Persistence: Timescale and PostgreSQL support (see contrib repository for Cassandra, InfluxDB, and MongoDB).
- 🔄 Rules Engine (RE): Automate processes with flexible rules for decision-making.
- 🚨 Alarms and Triggers: Immediate notifications for critical IoT events.
- 📅 Scheduled Actions: Plan and execute tasks at predefined times.
- 📝 Audit Logs: Maintain a detailed history of platform activities for compliance and debugging.
- 📊 Platform Logging and Instrumentation: Integrated with Prometheus and OpenTelemetry.
- ⚡ Event Sourcing: Streamlined architecture for real-time IoT event processing.
- 🐳 Container-Based Deployment: Fully compatible with Docker and Kubernetes.
- 🌍 Edge and IoT Ready: Agent and Export services for managing remote IoT gateways.
- 🛠️ Developer Tools: Comprehensive SDK and CLI for efficient development.
- 🏗️ Domain-Driven Design: High-quality codebase and extensive test coverage.
🔧 Install
Clone the repository and start the services:
git clone https://github.com/absmach/magistrala.git
cd magistrala
docker compose -f docker/docker-compose.yaml --env-file docker/.env up
Alternatively, use the Makefile for a simpler command:
make run args=-d
📤 Usage
Using the CLI:
Check the health of a specific service using the CLI:
make cli
./build/cli health <service>
Replace <service> with the name of the service you want to check.
Using Curl:
Alternatively, use a simple HTTP GET request to check the platform's health:
curl -X GET http://localhost:8080/health
For additional usage examples and advanced configurations, visit the official documentation.
📚 Documentation
Complete documentation is available at the Magistrala official docs page.
For CLI usage details, visit the CLI Documentation.
🌐 Community and Contributing
Join the community and contribute to the future of IoT middleware:
📜 License
Magistrala is open-source software licensed under the Apache-2.0 license. Contributions are welcome and encouraged!
💼 Professional Support
Need help deploying Magistrala or integrating it into your systems? Contact Abstract Machines for expert guidance and support.
Documentation
¶
Overview ¶
package magistrala acts as an umbrella package containing multiple different microservices and defines all shared domain concepts.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package alarms contains domain concept definitions needed to support Alarms service feature, i.e.
|
Package alarms contains domain concept definitions needed to support Alarms service feature, i.e. |
|
api
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
|
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations. |
|
middleware
Package middleware provides middleware for the alarms service.
|
Package middleware provides middleware for the alarms service. |
|
Package bootstrap contains the domain concept definitions needed to support SuperMQ bootstrap service functionality.
|
Package bootstrap contains the domain concept definitions needed to support SuperMQ bootstrap service functionality. |
|
api
Package api contains implementation of bootstrap service HTTP API.
|
Package api contains implementation of bootstrap service HTTP API. |
|
events
Package events provides the domain concept definitions needed to support bootstrap events functionality.
|
Package events provides the domain concept definitions needed to support bootstrap events functionality. |
|
events/consumer
Package consumer contains events consumer for events published by Bootstrap service.
|
Package consumer contains events consumer for events published by Bootstrap service. |
|
events/producer
Package producer contains the domain events needed to support event sourcing of Bootstrap service actions.
|
Package producer contains the domain events needed to support event sourcing of Bootstrap service actions. |
|
postgres
Package postgres contains repository implementations using PostgreSQL as the underlying database.
|
Package postgres contains repository implementations using PostgreSQL as the underlying database. |
|
tracing
Package tracing provides tracing instrumentation for SuperMQ Users service.
|
Package tracing provides tracing instrumentation for SuperMQ Users service. |
|
cmd
|
|
|
alarms
command
|
|
|
bootstrap
command
Package main contains bootstrap main function to start the bootstrap service.
|
Package main contains bootstrap main function to start the bootstrap service. |
|
cli
command
Package main contains cli main function to run the cli.
|
Package main contains cli main function to run the cli. |
|
postgres-reader
command
Package main contains postgres-reader main function to start the postgres-reader service.
|
Package main contains postgres-reader main function to start the postgres-reader service. |
|
postgres-writer
command
Package main contains postgres-writer main function to start the postgres-writer service.
|
Package main contains postgres-writer main function to start the postgres-writer service. |
|
provision
command
Package main contains provision main function to start the provision service.
|
Package main contains provision main function to start the provision service. |
|
re
command
Package main contains rule engine main function to start the service.
|
Package main contains rule engine main function to start the service. |
|
reports
command
Package main contains reports main function to start the service.
|
Package main contains reports main function to start the service. |
|
timescale-reader
command
Package main contains timescale-reader main function to start the timescale-reader service.
|
Package main contains timescale-reader main function to start the timescale-reader service. |
|
timescale-writer
command
Package main contains timescale-writer main function to start the timescale-writer service.
|
Package main contains timescale-writer main function to start the timescale-writer service. |
|
Package consumers contain the domain concept definitions needed to support SuperMQ consumer services functionality.
|
Package consumers contain the domain concept definitions needed to support SuperMQ consumer services functionality. |
|
notifiers
Package notifiers contain the domain concept definitions needed to support SuperMQ notifications functionality.
|
Package notifiers contain the domain concept definitions needed to support SuperMQ notifications functionality. |
|
notifiers/api
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
|
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations. |
|
notifiers/postgres
Package postgres contains repository implementations using PostgreSQL as the underlying database.
|
Package postgres contains repository implementations using PostgreSQL as the underlying database. |
|
notifiers/smpp
Package smpp contains the domain concept definitions needed to support Magistrala SMS notifications.
|
Package smpp contains the domain concept definitions needed to support Magistrala SMS notifications. |
|
notifiers/tracing
Package tracing provides tracing instrumentation for SuperMQ WebSocket adapter service.
|
Package tracing provides tracing instrumentation for SuperMQ WebSocket adapter service. |
|
writers
Package writers contain the domain concept definitions needed to support SuperMQ writer services functionality.
|
Package writers contain the domain concept definitions needed to support SuperMQ writer services functionality. |
|
writers/api
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
|
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations. |
|
writers/postgres
Package postgres contains repository implementations using Postgres as the underlying database.
|
Package postgres contains repository implementations using Postgres as the underlying database. |
|
writers/timescale
Package timescale contains repository implementations using Timescale as the underlying database.
|
Package timescale contains repository implementations using Timescale as the underlying database. |
|
internal
|
|
|
clients
Package clients contains the domain concept definitions needed to support Magistrala clients functionality for example: postgres, redis, grpc, jaeger.
|
Package clients contains the domain concept definitions needed to support Magistrala clients functionality for example: postgres, redis, grpc, jaeger. |
|
clients/redis
Package redis contains the domain concept definitions needed to support Magistrala redis cache functionality.
|
Package redis contains the domain concept definitions needed to support Magistrala redis cache functionality. |
|
email
Package email contains the domain concept definitions needed to support Magistrala email functionality.
|
Package email contains the domain concept definitions needed to support Magistrala email functionality. |
|
Package pkg contains library packages used by Magistrala services and external services that integrate with Magistrala.
|
Package pkg contains library packages used by Magistrala services and external services that integrate with Magistrala. |
|
errors
Package errors contains Magistrala errors definitions.
|
Package errors contains Magistrala errors definitions. |
|
prometheus
Package prometheus provides a framework for defining and collecting metrics for prometheus.
|
Package prometheus provides a framework for defining and collecting metrics for prometheus. |
|
sdk
Package sdk contains Magistrala SDK.
|
Package sdk contains Magistrala SDK. |
|
Package provision contains domain concept definitions needed to support Provision service feature, i.e.
|
Package provision contains domain concept definitions needed to support Provision service feature, i.e. |
|
api
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
|
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations. |
|
Package re contain the domain concept definitions needed to support Magistrala Rule Egine services functionality.
|
Package re contain the domain concept definitions needed to support Magistrala Rule Egine services functionality. |
|
api
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
|
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations. |
|
events
Package events provides the domain concept definitions needed to support clients events functionality.
|
Package events provides the domain concept definitions needed to support clients events functionality. |
|
Package readers provides a set of readers for various formats.
|
Package readers provides a set of readers for various formats. |
|
api
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
|
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations. |
|
api/grpc
Package grpc contains implementation of Readers service gRPC API.
|
Package grpc contains implementation of Readers service gRPC API. |
|
middleware
Package middleware provides middleware for Magistrala Readers service.
|
Package middleware provides middleware for Magistrala Readers service. |
|
postgres
Package postgres contains repository implementations using Postgres as the underlying database.
|
Package postgres contains repository implementations using Postgres as the underlying database. |
|
timescale
Package timescale contains repository implementations using Timescale as the underlying database.
|
Package timescale contains repository implementations using Timescale as the underlying database. |
|
api
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
|
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations. |
|
Package tools contains tools for SuperMQ.
|
Package tools contains tools for SuperMQ. |
|
e2e
Package e2e contains entry point for end-to-end tests.
|
Package e2e contains entry point for end-to-end tests. |
|
e2e/cmd
command
Package main contains e2e tool for testing SuperMQ.
|
Package main contains e2e tool for testing SuperMQ. |
|
mqtt-bench
Package bench contains benchmarking tool for MQTT broker.
|
Package bench contains benchmarking tool for MQTT broker. |
|
mqtt-bench/cmd
command
Package main contains the entry point of the mqtt-bench tool.
|
Package main contains the entry point of the mqtt-bench tool. |
|
provision
Package provision is a simple utility to create a list of channels and clients connected to these channels with possibility to create certificates for mTLS use case.
|
Package provision is a simple utility to create a list of channels and clients connected to these channels with possibility to create certificates for mTLS use case. |
|
provision/cmd
command
Package main contains entry point for provisioning tool.
|
Package main contains entry point for provisioning tool. |
Click to show internal directories.
Click to hide internal directories.