Skip to content

Commit 14282fb

Browse files
draskodrasko
authored
Update README.md (#25)
1 parent a34df79 commit 14282fb

File tree

1 file changed

+71
-143
lines changed

1 file changed

+71
-143
lines changed

‎README.md

Lines changed: 71 additions & 143 deletions
Original file line numberDiff line numberDiff line change
@@ -1,191 +1,119 @@
1-
# Magistrala
1+
<div align="center">
22

3-
[![Check License Header](https://github.com/absmach/magistrala/actions/workflows/check-license.yaml/badge.svg?branch=main)](https://github.com/absmach/magistrala/actions/workflows/check-license.yaml)
4-
[![Check the consistency of generated files](https://github.com/absmach/magistrala/actions/workflows/check-generated-files.yml/badge.svg?branch=main)](https://github.com/absmach/magistrala/actions/workflows/check-generated-files.yml)
5-
[![Continuous Delivery](https://github.com/absmach/magistrala/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/absmach/magistrala/actions/workflows/build.yml)
6-
[![go report card][grc-badge]][grc-url]
7-
[![coverage][cov-badge]][cov-url]
8-
[![license][license]](LICENSE)
9-
[![chat][gitter-badge]][gitter]
3+
# Magistrala
4+
5+
**A Modern IoT Platform Built on SuperMQ**
6+
7+
**Scalable • Secure • Open-Source**
8+
9+
[![Check License Header](https://github.com/absmach/magistrala/actions/workflows/check-license.yaml/badge.svg?branch=main)](https://github.com/absmach/magistrala/actions/workflows/check-license.yaml)
10+
[![Continuous Delivery](https://github.com/absmach/magistrala/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/absmach/magistrala/actions/workflows/build.yml)
11+
[![Go Report Card](https://goreportcard.com/badge/github.com/absmach/magistrala)](https://goreportcard.com/report/github.com/absmach/magistrala)
12+
[![Coverage](https://codecov.io/gh/absmach/magistrala/graph/badge.svg?token=SEMDAO3L09)](https://codecov.io/gh/absmach/magistrala)
13+
[![License](https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square)](LICENSE)
14+
[![Matrix](https://img.shields.io/matrix/magistrala:matrix.org?style=flat-square)](https://matrix.to/#/#magistrala:matrix.org)
15+
16+
### [Guide](https://docs.magistrala.abstractmachines.fr) | [Contributing](CONTRIBUTING.md) | [Website](https://abstractmachines.fr/magistrala.html) | [Chat](https://matrix.to/#/#magistrala:matrix.org)
1017

11-
![banner][banner]
18+
Made with ❤️ by [Abstract Machines](https://abstractmachines.fr/)
1219

13-
Magistrala is modern, scalable, secure, open-source, and patent-free IoT cloud platform written in Go.
20+
</div>
1421

15-
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.
1622

17-
For more details, check out the [official documentation][docs].
18-
For extra bits and services see [our contrib repository][contrib].
23+
## Introduction 🌍
1924

20-
## Features
25+
Magistrala is a cutting-edge, open-source IoT cloud platform built on top of [SuperMQ](https://github.com/absmach/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.
2126

22-
- Multi-protocol connectivity and bridging (HTTP, MQTT, WebSocket and CoAP; see [contrib repository][contrib] for LoRa and OPC UA)
23-
- Device management and provisioning (Zero Touch provisioning)
24-
- Mutual TLS Authentication (mTLS) using X.509 Certificates
25-
- Fine-grained access control (policies, ABAC/RBAC)
26-
- Message persistence (Timescale and PostgresSQL - see [contrib repository][contrib] for Cassandra, InfluxDB, and MongoDB support)
27-
- Platform logging and instrumentation support (Prometheus and OpenTelemetry)
28-
- Event sourcing
29-
- Container-based deployment using [Docker][docker] and [Kubernetes][kubernetes]
30-
- Edge [Agent][agent] and [Export][export] services for remote IoT gateway management and edge computing
31-
- SDK
32-
- CLI
33-
- Small memory footprint and fast execution
34-
- Domain-driven design architecture, high-quality code and test coverage
27+
### Key Benefits:
28+
- **Unified IoT Management**: Connect sensors, actuators, and applications over various network protocols.
29+
- **Scalability and Performance**: Designed to handle enterprise-grade IoT deployments.
30+
- **Secure by Design**: Features such as mutual TLS authentication and fine-grained access control.
31+
- **Open-Source Freedom**: Patent-free, community-driven, and designed for extensibility.
3532

36-
## Prerequisites
3733

38-
The following are needed to run Magistrala:
34+
## ✨ Features
3935

40-
- [Docker](https://docs.docker.com/install/) (version 26.0.0)
36+
- 🏢 **Multi-Tenancy**: Support for managing multiple independent domains seamlessly.
37+
- 👥 **Multi-User Platform**: Unlimited organizational hierarchies and user roles for streamlined collaboration.
38+
- 🌐 **Multi-Protocol Connectivity**: HTTP, MQTT, WebSocket, CoAP, and more (see [contrib repository](https://www.github.com/absmach/mg-contrib) for LoRa and OPC UA).
39+
- 💻 **Device Management and Provisioning**: Including Zero-Touch provisioning for seamless device onboarding.
40+
- 🛡️ **Mutual TLS Authentication (mTLS)**: Secure communication using X.509 certificates.
41+
- 📜 **Fine-Grained Access Control**: Support for ABAC and RBAC policies.
42+
- 💾 **Message Persistence**: Timescale and PostgreSQL support (see [contrib repository](https://www.github.com/absmach/mg-contrib) for Cassandra, InfluxDB, and MongoDB).
43+
- 🔄 **Rules Engine (RE)**: Automate processes with flexible rules for decision-making.
44+
- 🚨 **Alarms and Triggers**: Immediate notifications for critical IoT events.
45+
- 📅 **Scheduled Actions**: Plan and execute tasks at predefined times.
46+
- 📝 **Audit Logs**: Maintain a detailed history of platform activities for compliance and debugging.
47+
- 📊 **Platform Logging and Instrumentation**: Integrated with Prometheus and OpenTelemetry.
48+
- ⚡ **Event Sourcing**: Streamlined architecture for real-time IoT event processing.
49+
- 🐳 **Container-Based Deployment**: Fully compatible with Docker and Kubernetes.
50+
- 🌍 **Edge and IoT Ready**: Agent and Export services for managing remote IoT gateways.
51+
- 🛠️ **Developer Tools**: Comprehensive SDK and CLI for efficient development.
52+
- 🏗️ **Domain-Driven Design**: High-quality codebase and extensive test coverage.
4153

42-
Developing Magistrala will also require:
4354

44-
- [Go](https://golang.org/doc/install) (version 1.21)
45-
- [Protobuf](https://github.com/protocolbuffers/protobuf#protocol-compiler-installation) (version 25.1)
55+
## 🔧 Install
4656

47-
## Install
48-
49-
Once the prerequisites are installed, execute the following commands from the project's root:
57+
Clone the repository and start the services:
5058

5159
```bash
52-
docker compose -f docker/docker-compose.yml --env-file docker/.env -p git_github_com_absmach_magistrala_git_ up
60+
git clone https://github.com/absmach/magistrala.git
61+
cd magistrala
62+
docker compose -f docker/docker-compose.yml --env-file docker/.env up
5363
```
5464

55-
This will bring up the Magistrala docker services and interconnect them. This command can also be executed using the project's included Makefile:
65+
Alternatively, use the Makefile for a simpler command:
5666

5767
```bash
5868
make run
5969
```
6070

61-
If you want to run services from specific release checkout code from github and make sure that
62-
`MG_RELEASE_TAG` in [.env](.env) is being set to match the release version
63-
64-
```bash
65-
git checkout tags/<release_number> -b <release_number>
66-
# e.g. `git checkout tags/0.13.0 -b 0.13.0`
67-
```
68-
69-
Check that `.env` file contains:
70-
71-
```bash
72-
MG_RELEASE_TAG=<release_number>
73-
```
74-
75-
> `docker-compose` should be used for development and testing deployments. For production we suggest using [Kubernetes](https://docs.magistrala.abstractmachines.fr/kubernetes).
7671

77-
## Usage
72+
## 📤 Usage
7873

79-
The quickest way to start using Magistrala is via the CLI. The latest version can be downloaded from the [official releases page][releases].
74+
#### Using the CLI:
8075

81-
It can also be built and used from the project's root directory:
76+
Check the health of a specific service using the CLI:
8277

8378
```bash
8479
make cli
85-
./build/cli version
80+
./build/cli health <service>
8681
```
8782

88-
Additional details on using the CLI can be found in the [CLI documentation](https://docs.magistrala.abstractmachines.fr/cli).
89-
90-
## Documentation
91-
92-
Official documentation is hosted at [Magistrala official docs page][docs]. Documentation is auto-generated, checkout the instructions on [official docs repository](https://github.com/absmach/magistrala-docs):
93-
94-
If you spot an error or a need for corrections, please let us know - or even better: send us a PR.
83+
Replace `<service>` with the name of the service you want to check.
9584

96-
## Authors
85+
#### Using Curl:
9786

98-
Main architect and BDFL of Magistrala project is [@drasko][drasko].
87+
Alternatively, use a simple HTTP GET request to check the platform's health:
9988

100-
Additionally, [@nmarcetic][nikola] and [@janko-isidorovic][janko] assured overall architecture and design, while [@manuio][manu] and [@darkodraskovic][darko] helped with crafting initial implementation and continuously worked on the project evolutions.
101-
102-
Besides them, Magistrala is constantly improved and actively developed by [@anovakovic01][alex], [@dusanb94][dusan], [@srados][sava], [@gsaleh][george], [@blokovi][iva], [@chombium][kole], [@mteodor][mirko], [@rodneyosodo][rodneyosodo] and a large set of contributors.
103-
104-
Maintainers are listed in [MAINTAINERS](MAINTAINERS) file.
105-
106-
The Magistrala team would like to give special thanks to [@mijicd][dejan] for his monumental work on designing and implementing a highly improved and optimized version of the platform, and [@malidukica][dusanm] for his effort on implementing the initial user interface.
107-
108-
## Professional Support
109-
110-
There are many companies offering professional support for the Magistrala system.
111-
112-
If you need this kind of support, best is to reach out to [@drasko][drasko] directly, and he will point you out to the best-matching support team.
113-
114-
## Contributing
115-
116-
Thank you for your interest in Magistrala and the desire to contribute!
117-
118-
1. Take a look at our [open issues](https://github.com/absmach/magistrala/issues). The [good-first-issue](https://github.com/absmach/magistrala/labels/good-first-issue) label is specifically for issues that are great for getting started.
119-
2. Checkout the [contribution guide](CONTRIBUTING.md) to learn more about our style and conventions.
120-
3. Make your changes compatible to our workflow.
121-
122-
Also, explore our [contrib][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.
89+
```bash
90+
curl -X GET http://localhost:8080/health
91+
```
12392

124-
### We're Hiring
93+
For additional usage examples and advanced configurations, visit the [official documentation](https://docs.magistrala.abstractmachines.fr).
12594

126-
You like Magistrala 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][drasko] - he will contact you back.
12795

128-
> The best way to grab our attention is, of course, by sending PRs :sunglasses:.
96+
## 📚 Documentation
12997

130-
## Community
98+
Complete documentation is available at the [Magistrala official docs page](https://docs.magistrala.abstractmachines.fr).
13199

132-
- [Google group][forum]
133-
- [Gitter][gitter]
134-
- [Twitter][twitter]
100+
For CLI usage details, visit the [CLI Documentation](https://docs.magistrala.abstractmachines.fr/cli).
135101

136-
## License
137102

138-
[Apache-2.0](LICENSE)
103+
## 🌐 Community and Contributing
139104

140-
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fabsmach%2Fmagistrala.svg?type=large&issueType=license)](https://app.fossa.com/projects/git%2Bgithub.com%2Fabsmach%2Fmagistrala?ref=badge_large&issueType=license)
141-
## Data Collection for Magistrala
105+
Join the community and contribute to the future of IoT middleware:
142106

143-
Magistrala 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 Magistrala and is not used with any malicious intent. The deployment summary can be found on our [website][callhome].
107+
- [Open Issues](https://github.com/absmach/magistrala/issues)
108+
- [Contribution Guide](CONTRIBUTING.md)
109+
- [Matrix Chat](https://matrix.to/#/#magistrala:matrix.org)
144110

145-
The collected data includes:
146111

147-
- **IP Address** - Used for approximate location information on deployments.
148-
- **Services Used** - To understand which features are popular and prioritize future developments.
149-
- **Last Seen Time** - To ensure the stability and availability of Magistrala.
150-
- **Magistrala Version** - To track the software version and deliver relevant updates.
112+
## 📜 License
151113

152-
We take your privacy and data security seriously. All data collected is handled in accordance with our stringent privacy policies and industry best practices.
114+
Magistrala is open-source software licensed under the [Apache-2.0](LICENSE) license. Contributions are welcome and encouraged!
153115

154-
Data collection is on by default and can be disabled by setting the env variable:
155-
`MG_SEND_TELEMETRY=false`
156116

157-
By utilizing Magistrala, you actively contribute to its improvement. Together, we can build a more robust and efficient IoT platform. Thank you for your trust in Magistrala!
117+
## 💼 Professional Support
158118

159-
[banner]: https://github.com/absmach/magistrala-docs/blob/main/docs/img/gopherBanner.jpg
160-
[docs]: https://docs.magistrala.abstractmachines.fr
161-
[docker]: https://www.docker.com
162-
[forum]: https://groups.google.com/forum/#!forum/mainflux
163-
[gitter]: https://gitter.im/absmach/magistrala?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
164-
[gitter-badge]: https://badges.gitter.im/Join%20Chat.svg
165-
[grc-badge]: https://goreportcard.com/badge/github.com/absmach/magistrala
166-
[grc-url]: https://goreportcard.com/report/github.com/absmach/magistrala
167-
[cov-badge]: https://codecov.io/gh/absmach/magistrala/graph/badge.svg?token=SEMDAO3L09
168-
[cov-url]: https://codecov.io/gh/absmach/magistrala
169-
[license]: https://img.shields.io/badge/license-Apache%20v2.0-blue.svg
170-
[twitter]: https://twitter.com/absmach
171-
[agent]: https://github.com/absmach/agent
172-
[export]: https://github.com/absmach/export
173-
[kubernetes]: https://kubernetes.io/
174-
[releases]: https://github.com/absmach/magistrala/releases
175-
[drasko]: https://github.com/drasko
176-
[nikola]: https://github.com/nmarcetic
177-
[dejan]: https://github.com/mijicd
178-
[manu]: https://github.com/manuIO
179-
[darko]: https://github.com/darkodraskovic
180-
[janko]: https://github.com/janko-isidorovic
181-
[alex]: https://github.com/anovakovic01
182-
[dusan]: https://github.com/dborovcanin
183-
[sava]: https://github.com/srados
184-
[george]: https://github.com/gesaleh
185-
[iva]: https://github.com/blokovi
186-
[kole]: https://github.com/chombium
187-
[dusanm]: https://github.com/malidukica
188-
[mirko]: https://github.com/mteodor
189-
[rodneyosodo]: https://github.com/rodneyosodo
190-
[callhome]: https://deployments.magistrala.abstractmachines.fr/
191-
[contrib]: https://www.github.com/absmach/mg-contrib
119+
Need help deploying Magistrala or integrating it into your systems? Contact **[Abstract Machines](https://abstractmachines.fr/)** for expert guidance and support.

0 commit comments

Comments
 (0)