mirror of
https://github.com/absmach/supermq.git
synced 2026-06-23 06:40:19 +00:00
MF-899 - Update README and official docs (#910)
* Update root README.md Signed-off-by: nwneisen <nwneisen@gmail.com> * Update official documents Signed-off-by: nwneisen <nwneisen@gmail.com> * Move docker template version location Signed-off-by: nwneisen <nwneisen@gmail.com> * Move template to dev guide and remove bold Signed-off-by: nwneisen <nwneisen@gmail.com> * Remove double spaces after periods Signed-off-by: nwneisen <nwneisen@gmail.com> * Change repo to repository Signed-off-by: nwneisen <nwneisen@gmail.com>
This commit is contained in:
Nick Neisen
committed by
Dušan Borovčanin
Dušan Borovčanin
parent
fec058c614
commit
5f5d7e4cfa
@@ -8,7 +8,7 @@
|
||||
|
||||
![banner][banner]
|
||||
|
||||
Mainflux is modern, scalable, secure open source and patent-free IoT cloud platform written in Go.
|
||||
Mainflux is modern, scalable, secure, open-source, and patent-free IoT cloud platform written in Go.
|
||||
|
||||
It accepts user and thing 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
|
||||
@@ -17,10 +17,11 @@ for building complex IoT solutions.
|
||||
For more details, check out the [official documentation][docs].
|
||||
|
||||
Mainflux is member of the [Linux Foundation][lf] and an active contributor
|
||||
to the [EdgeX Foundry][edgex] project. It has been made with :heart: by [Mainflux Labs company][company],
|
||||
to the [EdgeX Foundry][edgex] project. It has been made with :heart: by [Mainflux Labs][company],
|
||||
which maintains the project and offers professional services around it.
|
||||
|
||||
## 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
|
||||
@@ -35,40 +36,59 @@ which maintains the project and offers professional services around it.
|
||||
- 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](https://docs.docker.com/install/) (version 18.09)
|
||||
- [Docker compose](https://docs.docker.com/compose/install/) (version 1.24.1)
|
||||
|
||||
Developing Mainflux will also require:
|
||||
|
||||
- [Go](https://golang.org/doc/install) (version 1.13.3)
|
||||
- [Protobuf](https://github.com/protocolbuffers/protobuf#protocol-compiler-installation) (version 3.6.1)
|
||||
|
||||
## Install
|
||||
Before proceeding, install the following prerequisites:
|
||||
|
||||
- [Docker](https://docs.docker.com/install/)
|
||||
- [Docker compose](https://docs.docker.com/compose/install/)
|
||||
|
||||
Once everything is installed, execute the following commands from project root:
|
||||
Once the prerequisites are installed, execute the following commands from the project's root:
|
||||
|
||||
```bash
|
||||
docker-compose -f docker/docker-compose.yml up -d
|
||||
docker-compose -f docker/docker-compose.yml -f docker/aedes.yml up
|
||||
```
|
||||
|
||||
This will bring up all Mainflux dockers and inter-connect them in the composition.
|
||||
This will bring up the Mainflux docker services and interconnect them. This command can also be executed using the project's included Makefile:
|
||||
|
||||
```bash
|
||||
make run
|
||||
```
|
||||
|
||||
## Usage
|
||||
Best way to quickstart using Mainflux is via CLI:
|
||||
```
|
||||
|
||||
The quickest way to start using Mainflux is via the CLI. The latest version can be downloaded from the [official releases page][rel].
|
||||
|
||||
It can also be built and used from the project's root directory:
|
||||
|
||||
```bash
|
||||
make cli
|
||||
./build/mainflux-cli version
|
||||
```
|
||||
|
||||
> Mainflux CLI can also be downloaded as a tarball from [offical release page][rel]
|
||||
|
||||
If this works, head to [official documentation][docs] to understand Mainflux provisioning and messaging.
|
||||
Additional details on using the CLI can be found in the [CLI documentation](https://mainflux.readthedocs.io/en/latest/cli/).
|
||||
|
||||
## Documentation
|
||||
Official documentation is hosted at [Mainflux Read The Docs page][docs].
|
||||
|
||||
Documentation is auto-generated from Markdown files in `./docs` directory.
|
||||
If you spot an error or need for corrections, please let us know - or even better: send us a PR.
|
||||
Official documentation is hosted at [Mainflux Read The Docs page][docs]. Documentation is auto-generated from Markdown files in `./docs` directory. These can be viewed locally by [installing mkdocs](https://www.mkdocs.org/#installation) and running the command:
|
||||
|
||||
```bash
|
||||
mkdocs serve
|
||||
```
|
||||
|
||||
If you spot an error or a need for corrections, please let us know - or even better: send us a PR.
|
||||
|
||||
Additional practical information, news and tutorials can be found on the [Mainflux blog][blog].
|
||||
|
||||
## Authors
|
||||
|
||||
Main architect and BDFL of Mainflux project is [@drasko][drasko].
|
||||
|
||||
Additionally, [@nmarcetic][nikola] and [@janko-isidorovic][janko] assured
|
||||
@@ -81,29 +101,33 @@ developed by [@anovakovic01][alex], [@dusanb94][dusan], [@srados][sava],
|
||||
|
||||
Maintainers are listed in [MAINTAINERS](MAINTAINERS) file.
|
||||
|
||||
Mainflux team would like to give special thanks to [@mijicd][dejan] for his monumental work
|
||||
on designing and implementing highly improved and optimized version of the platform,
|
||||
and [@malidukica][dusanm] for his effort on implementing initial user interface.
|
||||
The Mainflux 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.
|
||||
|
||||
## Contributing
|
||||
Thank you for your interest in Mainflux and wish to contribute!
|
||||
|
||||
1. Take a look at our [open issues](https://github.com/mainflux/mainflux/issues).
|
||||
Thank you for your interest in Mainflux and the desire to contribute!
|
||||
|
||||
1. Take a look at our [open issues](https://github.com/mainflux/mainflux/issues). The [good-first-issue](https://github.com/mainflux/mainflux/labels/good-first-issue) label is specifically for issues that are great for getting started.
|
||||
2. Checkout the [contribution guide](CONTRIBUTING.md) to learn more about our style and conventions.
|
||||
3. Make your changes compatible to our workflow.
|
||||
|
||||
### We're Hiring
|
||||
|
||||
If you are interested in working professionally on Mainflux,
|
||||
please head to company's [careers page][careers] or shoot us an e-mail at <careers@mainflux.com>.
|
||||
|
||||
Note that the best way to grab our attention is by sending PRs :sunglasses:.
|
||||
>The best way to grab our attention is by sending PRs :sunglasses:.
|
||||
|
||||
## Community
|
||||
|
||||
- [Google group][forum]
|
||||
- [Gitter][gitter]
|
||||
- [Twitter][twitter]
|
||||
|
||||
## License
|
||||
|
||||
[Apache-2.0](LICENSE)
|
||||
|
||||
[banner]: https://github.com/mainflux/mainflux/blob/master/docs/img/gopherBanner.jpg
|
||||
|
||||
+37
-14
@@ -1,43 +1,49 @@
|
||||
## Getting Mainflux
|
||||
|
||||
Mainflux can be fetched from the official [Mainflux GitHub repository](https://github.com/Mainflux/mainflux):
|
||||
Mainflux source can be found in the official [Mainflux GitHub repository](https://github.com/Mainflux/mainflux). You should fork this repository in order to make changes to the project. The forked version of the repository should be cloned using the following:
|
||||
|
||||
```
|
||||
go get github.com/mainflux/mainflux
|
||||
```bash
|
||||
git clone <forked repository> $GOPATH/src/github.com/mainflux/mainflux
|
||||
cd $GOPATH/src/github.com/mainflux/mainflux
|
||||
```
|
||||
|
||||
## Building
|
||||
|
||||
### Prerequisites
|
||||
Make sure that you have [Protocol Buffers](https://developers.google.com/protocol-buffers/) compiler (`protoc`) installed.
|
||||
|
||||
Make sure that you have [Protocol Buffers](https://developers.google.com/protocol-buffers/) (version 3.6.1) compiler (`protoc`) installed.
|
||||
|
||||
[Go Protobuf](https://github.com/golang/protobuf) installation instructions are [here](https://github.com/golang/protobuf#installation).
|
||||
Go Protobuf uses C bindings, so you will need to install [C++ protobuf](https://github.com/google/protobuf) as a prerequisite.
|
||||
Mainflux uses `Protocol Buffers for Go with Gadgets` to generate faster marshaling and unmarshaling Go code. Protocol Buffers for Go with Gadgets instalation instructions can be found (here)(https://github.com/gogo/protobuf).
|
||||
Mainflux uses `Protocol Buffers for Go with Gadgets` to generate faster marshaling and unmarshaling Go code. Protocol Buffers for Go with Gadgets installation instructions can be found [here](https://github.com/gogo/protobuf).
|
||||
|
||||
A copy of [Go](https://golang.org/doc/install) (version 1.13.3) and docker template (version 3.7) will also need to be installed on your system.
|
||||
|
||||
If any of these versions seem outdated, the latest can always be found in our [CI script](https://github.com/mainflux/mainflux/blob/master/scripts/ci.sh).
|
||||
|
||||
### Build All Services
|
||||
|
||||
Use `GNU Make` tool to build all Mainflux services:
|
||||
Use the *GNU Make* tool to build all Mainflux services:
|
||||
|
||||
```
|
||||
```bash
|
||||
make
|
||||
```
|
||||
|
||||
Build artefacts will be put in the `build` directory.
|
||||
Build artifacts will be put in the `build` directory.
|
||||
|
||||
> N.B. All Mainflux services are built as a statically linked binaries. This way they can be portable (transferred to any platform just by placing them there and running them) as they contain all needed libraries and do not relay on shared system libraries. This helps creating [FROM scratch](https://hub.docker.com/_/scratch/) dockers.
|
||||
|
||||
### Build Individual Microservice
|
||||
|
||||
Individual microservices can be built with:
|
||||
|
||||
```
|
||||
```bash
|
||||
make <microservice_name>
|
||||
```
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
```bash
|
||||
make http
|
||||
```
|
||||
|
||||
@@ -47,19 +53,19 @@ will build the HTTP Adapter microservice.
|
||||
|
||||
Dockers can be built with:
|
||||
|
||||
```
|
||||
```bash
|
||||
make dockers
|
||||
```
|
||||
|
||||
or individually with:
|
||||
|
||||
```
|
||||
```bash
|
||||
make docker_<microservice_name>
|
||||
```
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
```bash
|
||||
make docker_http
|
||||
```
|
||||
|
||||
@@ -83,6 +89,23 @@ make docker_dev_<microservice_name>
|
||||
|
||||
Commands `make dockers` and `make dockers_dev` are similar. The main difference is that building images in the development mode is done on the local machine, rather than an intermediate image, which makes building images much faster. Before running this command, corresponding binary needs to be built in order to make changes visible. This can be done using `make` or `make <service_name>` command. Commands `make dockers_dev` and `make docker_dev_<service_name>` should be used only for development to speed up the process of image building. **For deployment images, commands from section above should be used.**
|
||||
|
||||
### Suggested workflow
|
||||
|
||||
When the project is first cloned to your system, you will need to make sure and build all of the Mainflux services.
|
||||
|
||||
```bash
|
||||
make
|
||||
make dockers_dev
|
||||
```
|
||||
|
||||
As you develop and test changes, only the services related to your changes will need to be rebuilt. This will reduce compile time and create a much more enjoyable development experience.
|
||||
|
||||
```bash
|
||||
make <microservice_name>
|
||||
make docker_dev_<microservice_name>
|
||||
make run
|
||||
```
|
||||
|
||||
### Overriding the default docker-compose configuration
|
||||
Sometimes, depending on the use case and the user's needs it might be useful to override or add some extra parameters to the docker-compose configuration. These configuration changes can be done by specifying multiple compose files with the [docker-compose command line option -f](https://docs.docker.com/compose/reference/overview/) as described [here](https://docs.docker.com/compose/extends/).
|
||||
The following format of the `docker-compose` command can be used to extend or override the configuration:
|
||||
@@ -160,7 +183,7 @@ A shorthand to do this via `make` tool is:
|
||||
make proto
|
||||
```
|
||||
|
||||
> N.B. This must be done once at the beginning in order to generate protobuf Go structures needed for the build. However, if you don't change any of `.proto` files, this step is not mandatory, since all generated files are included in the repo (those are files with `.pb.go` extension).
|
||||
> N.B. This must be done once at the beginning in order to generate protobuf Go structures needed for the build. However, if you don't change any of `.proto` files, this step is not mandatory, since all generated files are included in the repository (those are files with `.pb.go` extension).
|
||||
|
||||
### Cross-compiling for ARM
|
||||
Mainflux can be compiled for ARM platform and run on Raspberry Pi or other similar IoT gateways, by following the instructions [here](https://dave.cheney.net/2015/08/22/cross-compilation-with-go-1-5) or [here](https://www.alexruf.net/golang/arm/raspberrypi/2016/01/16/cross-compile-with-go-1-5-for-raspberry-pi.html) as well as information
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
## Step 1 - Run the System
|
||||
Before proceeding, install the following prerequisites:
|
||||
|
||||
- [Docker](https://docs.docker.com/install/)
|
||||
- [Docker compose](https://docs.docker.com/compose/install/)
|
||||
- [Docker](https://docs.docker.com/install/) (version 18.09)
|
||||
- [Docker compose](https://docs.docker.com/compose/install/) (version 1.24.1)
|
||||
|
||||
Once everything is installed, execute the following command from project root:
|
||||
|
||||
@@ -14,10 +14,10 @@ This will start Mainflux docker composition, which will output the logs from the
|
||||
|
||||
## Step 2 - Install the CLI
|
||||
Open a new terminal from which you can interact with the running Mainflux system. The easiest way to do this is by using the Mainflux CLI,
|
||||
which can be downloaded as a tarball from GitHub (here we use release `0.7.0` but be sure to use the latest release):
|
||||
which can be downloaded as a tarball from GitHub (here we use release `0.9.0` but be sure to use the latest release):
|
||||
|
||||
```bash
|
||||
wget -O- https://github.com/mainflux/mainflux/releases/download/0.7.0/mainflux-cli_v0.7.0_linux-amd64.tar.gz | tar xvz -C $GOBIN
|
||||
wget -O- https://github.com/mainflux/mainflux/releases/download/0.9.0/mainflux-cli_v0.9.0_linux-amd64.tar.gz | tar xvz -C $GOBIN
|
||||
```
|
||||
|
||||
> Make sure that `$GOBIN` is added to your `$PATH` so that `mainflux-cli` command can be accessible system-wide
|
||||
@@ -31,7 +31,7 @@ mainflux-cli provision test
|
||||
This command actually creates a temporary testing user, logs it in, then creates two things and two channels on behalf of this user.
|
||||
This quickly provisions a Mainflux system with one simple testing scenario.
|
||||
|
||||
You can read more about system provisioning in a dedicated [Provisioning](./provisioning.md) chapter
|
||||
You can read more about system provisioning in the dedicated [Provisioning](./provisioning.md) chapter
|
||||
|
||||
Output of the command follows this pattern:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user