Warning

This repository is obsolete. All of its content has been merged to www.github.com/absmach/magistrala. Please use that repository for all active development.

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.

Installation 🛠️

There are multiple ways to run Magistrala. First, clone the repository and position to it:

git clone https://github.com/absmach/magistrala.git
cd magistrala

To run the latest stable (tagged) version, use:

# Run with latest stable tagged version
make run_stable

To run the latest version, use:

# Run with latest development version (from main branch)
make run_latest

The make run_stable command will:

• Checkout the repository to the latest git tag
• Update the version in the environment configuration
• Start the services with the stable release

Note: After running make run_stable, you'll be on a detached HEAD state. To return to your working branch:

git checkout main

Running on Apple Silicon (M1/M2/M3) Macs

When running Magistrala on Apple Silicon Macs, the Makefile will automatically detect your ARM64 architecture and build Docker images locally.

If using Docker Desktop:

1. Enable Apple Virtualization Framework: In Docker Desktop, go to:

   • Settings → General → Enable "Use the new Virtualization framework"

2. Enable Rosetta for x86_64 Emulation: In Docker Desktop, go to:

   • Settings → General → Enable "Use Rosetta for x86_64/amd64 emulation on Apple Silicon"

After enabling these options, restart Docker Desktop, then run make run_stable or make run_latest as usual.

📤 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:

• Open Issues
• Contribution Guide
• Matrix Chat

📜 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.