absmach / magistrala-docs

Magistrala documentation

Magistrala

[build][build]

This repo collects the collaborative work on Magistrala documentation. The official documentation is hosted at Magistrala Docs page. Documentation is auto-generated from Markdown files in this repo.

MkDocs is used to serve the docs locally with different theming.

Additional practical information about Magistrala system, news and tutorials can be found on the Magistrala blog.

Prerequisites

Install MkDocs

pip install mkdocs

Install

Doc repo can be fetched from GitHub:

git clone [email protected]:/absmach/magistrala-docs.git

Usage

Use MkDocs to serve documentation:

mkdocs serve

Then just point the browser to http://127.0.0.1:8000.

Contributing

Thank you for your interest in Magistrala 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. Check out the contribution guide to learn more about our style and conventions.
3. Make your changes compatible with our workflow.

Community

• Matrix
• Twitter

License

Apache-2.0

magistrala-docs's Issues

Add HTTP API curl request documentation

FEATURE REQUEST

2. Describe the feature you are requesting, as well as the possible use case(s) for it.

We need HTTP curl requests specifications and corresponding response examples.

3. Indicate the importance of this feature to you (must-have, should-have, nice-to-have).

Should-have

Add curl flag to cli docs

FEATURE REQUEST

1. Is there an open issue addressing this request? If it does, please add a "+1" reaction to the
   No

2. Describe the feature you are requesting, as well as the possible use case(s) for it.
   Add curl flag to the documentation. This would be helpful for users who are using the CLI.

3. Indicate the importance of this feature to you (must-have, should-have, nice-to-have).
   should-have

Policies documentation

FEATURE REQUEST

1. Is there an open issue addressing this request? If it does, please add a "+1" reaction to the
   existing issue, otherwise proceed to step 2.

2. Describe the feature you are requesting, as well as the possible use case(s) for it.
   Currently, there is no documentation regarding Policies. With the implementation of the initial Policies #1440, Policies must be documented.

3. Indicate the importance of this feature to you (must-have, should-have, nice-to-have).
   must-have

Update NATS prefix in storage.md

BUG REPORT

The latest modification (https://github.com/mainflux/mainflux/pull/1098) have also an impact on storage.md file.

Link is broken since it is in quotes

https://github.com/absmach/magistrala-docs/blame/111f0dc38fc93a586210ec354d61dd12d3d82a24/docs/dev-guide.md#L305

Correct Thing creation docs

FEATURE REQUEST

1. Is there an open issue addressing this request? If it does, please add a "+1" reaction to the
   existing issue, otherwise proceed to step 2.

2. Describe the feature you are requesting, as well as the possible use case(s) for it.

Add both creation approaches (single and bulk) to Things API reference.

3. Indicate the importance of this feature to you (must-have, should-have, nice-to-have).
   must-have

Getting started steps needs update for mainflux-cli

FEATURE REQUEST

I'm trying to explore the 'mainflux' by installing it on a personal laptop and during that process, I felt that getting started documentation needs a minor update to increase the user experience.

Also, there was an issue raised by the user before that they were not able to build the CLI because they tried without proper GOPATH and go get.

I too faced the same issue; it's good to update the doc with more detailed steps for the new users.

Also, I found that the images and volumes should be deleted if the volumes were created by the old releases as that may not be compatible with the new version.

Add new relation `guest`

FEATURE REQUEST

1. Is there an open issue addressing this request? If it does, please add a "+1" reaction to the
   existing issue, otherwise proceed to step 2.
   No
2. Describe the feature you are requesting, as well as the possible use case(s) for it.
   Add new relation guest
3. Indicate the importance of this feature to you (must-have, should-have, nice-to-have).
   must-have

Get Started CLI version update

BUG REPORT

1. What were you trying to achieve?

Go through the Get Started.

2. What are the expected results?

Reproducing the same results presented in the Get Started.

3. What are the received results?

mainflux-users | {"level":"warn","message":"Method register for user [email protected] took 2.043883ms to complete with error: password does not meet the requirements.","ts":"2021-11-22T16:59:49.275523438Z"}

4. What are the steps to reproduce the issue?

Go through the exact steps from the Get Started.

5. In what environment did you encounter the issue?

GOARCH=amd64

6. Additional information you deem important:

The problem is caused by the fact that CLI v0.9.0 uses the password "123" for that test which doesn't match the new default regex ^.{8,}.

It does say in the Get Started: here we use release 0.9.0 but be sure to use the latest release, however I would argue that the Get Started should work off the bat (just link the new version) or at least there should be a link to https://github.com/mainflux/mainflux/releases.

Secure HTTPS communications

BUG REPORT

1. What were you trying to achieve?
   Remove --insecure on curl because it is not necessary when the certificate is specified.

2. What are the expected results?
   Secured requests with the specified certificate.

3. What are the received results?
   Unsecured communication (possible man-in-the-middle attack).

4. What are the steps to reproduce the issue?
   Launch default docker-compose.

5. In what environment did you encounter the issue?
   Docker.

6. Additional information you deem important:
   NA

NOISSUE - Add Examples of Domain login using CLI

1. Is there an open issue addressing this request?
   No

2. Describe the feature you are requesting, as well as the possible use case(s) for it.
   Include examples of how to perform domain login using the CLI here: https://docs.magistrala.abstractmachines.fr/cli/. This would be useful for users who prefer or need to use the command line interface.

3. Indicate the importance of this feature to you (must-have, should-have, nice-to-have).
   Should-have feature.

BUG REPORT

1. What were you trying to achieve?

   • N/A, this is a feature request.

2. What are the expected results?

   • N/A, this is a feature request.

3. What are the received results?

   • N/A, this is a feature request.

4. What are the steps to reproduce the issue?

   • N/A, this is a feature request.

5. In what environment did you encounter the issue?

   • N/A, this is a feature request.

6. Additional information you deem important:

   • N/A, this is a feature request.

Use snake_case for Lora and OPC-UA metadata fields

Related to: https://github.com/mainflux/mainflux/issues/1129

Addons: trying to save messages into influxdb

I'm trying to save sent messages using addons (Influxdb) while using mqtt. My application works fine - the messages are sent and received, but when I try to read them, none are saved. I saw in one old example using http that I should add content type header, but mqtt doesn't have that option. I saw here something like having special topic "/ct" but I don't understand how to use this.

The mainflux I'm using is from April 29. this year. Writer and reader are installed successfully.

My apps are in python, so I'm using paho library.

Here is my code:

app sending data

app showing data (partially):

app trying to read the messages from influxdb:

Update default password (minimum password length to 8)

BUG REPORT

1. What were you trying to achieve?
   Change default password in Getting-started section.

2. What are the expected results?

3. What are the received results?

4. What are the steps to reproduce the issue?

5. In what environment did you encounter the issue?

6. Additional information you deem important:

Add indication about run CLI via a docker container

FEATURE REQUEST

1. Is there an open issue addressing this request? If it does, please add a "+1" reaction to the
   existing issue, otherwise proceed to step 2.
   Add indication about run CLI via a docker container.

2. Describe the feature you are requesting, as well as the possible use case(s) for it.

3. Indicate the importance of this feature to you (must-have, should-have, nice-to-have).

Document MQTT over WS

FEATURE REQUEST

1. Is there an open issue addressing this request? If it does, please add a "+1" reaction to the
   existing issue, otherwise proceed to step 2.
   No

2. Describe the feature you are requesting, as well as the possible use case(s) for it.

   Doc missing for MQTT over WS

3. Indicate the importance of this feature to you (must-have, should-have, nice-to-have).

must-have

Add the Connect method API doc - connecting one thing to one channel

FEATURE REQUEST

1. Is there an open issue addressing this request? If it does, please add a "+1" reaction to the
   existing issue, otherwise proceed to step 2.

2. Describe the feature you are requesting, as well as the possible use case(s) for it.
   Add second approach here

3. Indicate the importance of this feature to you (must-have, should-have, nice-to-have).
   Must-have

Remove WS and move Content Type from message payload to storage

WS part related to: https://github.com/mainflux/mainflux/issues/1087
Content type part related to: https://github.com/mainflux/mainflux/issues/1088

Port of Bootstrap service is wrong

BUG REPORT

1. What were you trying to achieve?
   The port define for Bootstrap service (8200) is wrong.

2. What are the expected results?

3. What are the received results?

4. What are the steps to reproduce the issue?

5. In what environment did you encounter the issue?

6. Additional information you deem important:

NOISSUE - WS port wrong on code example

BUG REPORT

1. What were you trying to achieve?
   Send a message over websockets using golang example

2. What are the expected results?
   successful message sent

3. What are the received results?
   Error connecting to Websocket Server: dial tcp [::1]:8190: connect: connection refused

4. What are the steps to reproduce the issue?
   https://github.com/mainflux/docs/blob/1b598be9ed63f8bc56a881219a477b5452950c18/docs/messaging.md?plain=1#L143

Port should be 8186
8. In what environment did you encounter the issue?

9. Additional information you deem important:

ES With NATS Jet Stream

FEATURE REQUEST

Document event streaming with NATS Jet Stream

Wrong redirection to Issues of this repository

BUG REPORT

1. What were you trying to achieve?
   The redirection to Issues of this repository is not right.

2. What are the expected results?
   NA

3. What are the received results?
   NA

4. What are the steps to reproduce the issue?
   NA

5. In what environment did you encounter the issue?
   NA

6. Additional information you deem important:
   NA

Kubernetes installation steps need an update

BUG REPORT

1. What were you trying to achieve?
   Install MF in Kubernetes cluster

2. What are the expected results?
   Successful installation of MF on Kubernetes by following the MF documentation

3. What are the received results?
   Couldn't install MF on Kubernetes via Helm

dramasam@Dineshs-MacBook-Pro mainflux % helm repo add stable https://kubernetes-charts.storage.googleapis.com/
Error: repo "https://kubernetes-charts.storage.googleapis.com/" is no longer available; try "https://charts.helm.sh/stable" instead
dramasam@Dineshs-MacBook-Pro mainflux % helm repo add stable https://charts.helm.sh/stable
"stable" has been added to your repositories
dramasam@Dineshs-MacBook-Pro mainflux % helm dependency update
Error: no repository definition for @bitnami, @bitnami, @bitnami, @bitnami, @bitnami, @bitnami, @bitnami, @bitnami, @bitnami, @bitnami, @bitnami, @bitnami. Please add them via 'helm repo add'

4. What are the steps to reproduce the issue?
   Follow the steps in https://mainflux.readthedocs.io/en/latest/kubernetes/

5. In what environment did you encounter the issue?
   😄 minikube v1.14.2 on Darwin 10.15.6
   ✨ Using the vmware driver based on existing profile
   👍 Starting control plane node minikube in cluster minikube
   🎉 minikube 1.17.1 is available! Download it: https://github.com/kubernetes/minikube/releases/tag/v1.17.1
   💡 To disable this notice, run: 'minikube config set WantUpdateNotification false'
   🔄 Restarting existing vmware VM for "minikube" ...
   🐳 Preparing Kubernetes v1.19.2 on Docker 19.03.12 ...
   🔗 Configuring Calico (Container Networking Interface) ...
   🔎 Verifying Kubernetes components...
   🌟 Enabled addons: storage-provisioner, default-storageclass
   🏄 Done! kubectl is now configured to use "minikube" by default

6. Additional information you deem important:
   dramasam@Dineshs-MacBook-Pro mainflux % helm repo add stable https://kubernetes-charts.storage.googleapis.com/
   Error: repo "https://kubernetes-charts.storage.googleapis.com/" is no longer available; try "https://charts.helm.sh/stable" instead
   dramasam@Dineshs-MacBook-Pro mainflux % helm repo add stable https://charts.helm.sh/stable
   "stable" has been added to your repositories
   dramasam@Dineshs-MacBook-Pro mainflux % helm dependency update
   Error: no repository definition for @bitnami, @bitnami, @bitnami, @bitnami, @bitnami, @bitnami, @bitnami, @bitnami, @bitnami, @bitnami, @bitnami, @bitnami. Please add them via 'helm repo add'

Correct and enhance CoAP doc

In the official CoAP docs authorization option is used, which is not correct - now we use auth.

Please correct this.

Additionally, please give several examples and explanations:

• Observation mode and how to use it
• What is CoAP CLI tool and how to use it

Give example of usage.

Fix documentation with new Auth service in provision page

BUG REPORT

After the merging of authz and authn service https://github.com/mainflux/mainflux/pull/1313, links to Auth doesn't work.

There is also some old information related to Authn in the kubernetes page.

Rename Relation : Viewer to Contributor

FEATURE REQUEST

1. Is there an open issue addressing this request? If it does, please add a "+1" reaction to the
   existing issue, otherwise proceed to step 2.

2. Describe the feature you are requesting, as well as the possible use case(s) for it.

3. Indicate the importance of this feature to you (must-have, should-have, nice-to-have).

BUG REPORT

1. What were you trying to achieve?

2. What are the expected results?

3. What are the received results?

4. What are the steps to reproduce the issue?

5. In what environment did you encounter the issue?

6. Additional information you deem important:

Online version of documentation doesn't match with latest commit

BUG REPORT

1. What were you trying to achieve?
   The latest version of Mainflux Read The Docs page does not match with latests commits.

2. What are the expected results?

3. What are the received results?

4. What are the steps to reproduce the issue?

5. In what environment did you encounter the issue?

6. Additional information you deem important:

Add docs for external ID

Update the document for the new feature which is described at https://github.com/mainflux/mainflux/issues/1425

Now the things API supports the creation of things with specified external ID.
Now the channels API supports the creation of the channels with specified external ID.