MG-4 - Update Magistrala Documentation with Docusaurus (#5)

* initial setUp

Signed-off-by: Musilah <[email protected]>

* confirm urls and pictures

Signed-off-by: Musilah <[email protected]>

* fix logo right branch

Signed-off-by: Musilah <[email protected]>

---------

Signed-off-by: Musilah <[email protected]>

.gitignore

@@ -1 +1,22 @@
 /site
+
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

CONTRIBUTING.md

@@ -40,23 +40,23 @@ Please adhere to the coding conventions used throughout the project. If in doubt
 To contribute to the project, [fork](https://help.github.com/articles/fork-a-repo/) it,
 clone your fork repository and configure the remotes:
 
-```
+```bash
 git clone https://github.com/<your-username>/docs.git
 cd docs
 git remote add upstream https://github.com/absmach/magistrala-docs.git
 ```
 
 If your cloned repository is behind the upstream commits, then get the latest changes from upstream:
 
-```
+```bash
 git checkout master
 git pull --rebase upstream master
 ```
 
 Create a new topic branch from `master` using the naming convention `MG-[issue-number]`
 to help us keep track of your contribution scope:
 
-```
+```bash
 git checkout -b MG-[issue-number]
 ```
 
@@ -73,13 +73,13 @@ and `user.email` git configs, you can sign your commit automatically with `git c
 
 Locally merge (or rebase) the upstream development branch into your topic branch:
 
-```
+```bash
 git pull --rebase upstream master
 ```
 
 Push your topic branch up to your fork:
 
-```
+```bash
 git push origin MG-[issue-number]
 ```
 

blog/authors.yml

@@ -0,0 +1,23 @@
+borovcanin:
+  name: 'Dusan borovcanin'
+  title: 'Software Engineer'
+  url: 'https://github.com/dborovcanin'
+
+draskovic:
+  name: 'Drasko Draskovic'
+  title: 'Software Engineer'
+  url: 'https://github.com/drasko'
+  email: '[email protected]'
+
+osodo:
+  name: 'Rodney Osodo'
+  title: 'Software Engineer'
+  url: 'http://rodneyosodo.com/'
+  socials:
+    twitter: 'https://twitter.com/b1ackd0t'
+
+musilah: 
+  name: 'Nataly Musilah'
+  title: 'Software Engineer'
+  url: 'https://github.com/Musilah'
+  email: '[email protected]'

blog/index.md

@@ -0,0 +1,18 @@
+---
+title: Welcome to the Magistrala Blog
+slug: /
+authors: osodo
+---
+
+## Blogs
+
+This section contains a list of blogs that are related to Magistrala. They have been published to the [Official Abstract Machines blog in Medium](https://medium.com/abstract-machines-blog).
+
+<!-- truncate -->
+
+## Featured Blogs
+
+- [What's New in Magistrala v0.14.0](./v0-14-0-release/v0-14-0-release.md)
+- [Extending Magistrala Users Repository](./kratos/kratos.md)
+- [Integrating OAuth2.0 with Magistrala](./oauth/oauth.md)
+- [Guide on using magistrala](./user-guide.md)

docs/blogs/kratos.md → blog/kratos/kratos.md

@@ -1,6 +1,19 @@
+---
+slug: extending-users-repository
+title: Extending Magistrala Users Repository
+authors: osodo
+description: Learn how Magistrala integrates with Ory Kratos to enhance user management, featuring MFA, password recovery, and admin APIs.
+tags: ['Magistrala', 'Kratos', 'User Management', 'Identity']
+---
+
+
 # Extending Magistrala Users Repository
 
-For the past few months, we have been working on integrating Magistrala with [Ory Kratos](https://www.ory.sh/docs/kratos/ory-kratos-intro) as the user management service. Ory Kratos is a cloud-native identity and user management system, which can be used as the user management service for Magistrala. Let's delve deeper into the myriad capabilities that Kratos brings to the forefront:
+For the past few months, we have been working on integrating Magistrala with [Ory Kratos](https://www.ory.sh/docs/kratos/ory-kratos-intro) as the user management service. Ory Kratos is a cloud-native identity and user management system, which can be used as the user management service for Magistrala. 
+
+<!-- truncate -->
+
+Let's delve deeper into the myriad capabilities that Kratos brings to the forefront:
 
 - self-service user login and registration. This is the ability to register and log in to the system without the need for an administrator.
 - multi-factor authentication with Time-based One-time Passwords (TOTP).
@@ -21,7 +34,7 @@ Go kit is a collection of Go packages that help you build robust, reliable, main
 
 we added an extra layer to most of our services called the `repository layer`. This crucial layer acts as the intermediary responsible for interfacing with the database, thus fostering a clean separation of concerns wherein the repository layer remains blissfully unaware of the intricacies of the transport layer.
 
-![Users Service Architecture](../img/blogs/kratos/architecture.png)
+![Users Service Architecture](./architecture.png)
 
 With this architecture, we can decouple the services from the database and make it easier to switch between different databases.
 

docs/blogs/oauth.md → blog/oauth/oauth.md

@@ -1,7 +1,18 @@
+---
+slug: integrating-oauth2
+title: Integrating OAuth2.0 with Magistrala
+authors: osodo
+description: Explore how Magistrala integrates OAuth2.0 to enhance authentication with support for Google and other providers.
+tags: ['OAuth2.0', 'Authentication', 'Magistrala', 'Google OAuth']
+---
+
+
 # Integrating OAuth2.0 with Magistrala
 
 Over the past months, we have been working on integrating OAuth2.0 with Magistrala. We are happy to announce that we have completed the integration and it is [now available](https://github.com/absmach/magistrala/pull/2103). We believe that this will open up a lot of possibilities for Magistrala and we are very excited about the future of Magistrala. We are planning to add more features to the OAuth2.0 integration in future releases. We are also planning to add support for more OAuth2.0 providers. This will enable users to use their preferred OAuth2.0 provider to authenticate with Magistrala.
 
+<!-- truncate -->
+
 [OAuth2.0](https://datatracker.ietf.org/doc/html/rfc6749) is an authorization framework that facilitates a third-party application to gain restricted access to another HTTP service. This can occur either by mediating an approval process between the resource owner and the HTTP service or by enabling the third-party application to autonomously acquire access. In OAuth2.0, a client requests access to a resource controlled by the resource owner and hosted by the resource server and is issued a different set of credentials than those of the resource owner. Instead of using the resource owner's credentials to access the resource, the client obtains an access token - a string representing the grant issued to the client by the resource owner. The client uses the access token to access the protected resources hosted by the resource server.
 
 In OAuth2.0, there are four roles:
@@ -29,11 +40,11 @@ The abstract OAuth2.0 flow is as follows:
 
 This flow is demonstrated in the following diagram:
 
-![Generic OAuth2.0 flow](../img/blogs/oauth/genericflow.png)
+![Generic OAuth2.0 flow](./genericflow.png)
 
 Magistrala can now be the resource server and Google as one of the authorization servers. We have implemented the OAuth2.0 [authorization code flow](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1). The authorization code flow is used to obtain an access and refresh token to authorize API requests. The UI client initiates the flow by redirecting the user to the authorization server(Google). The user authenticates and authorizes the client(Magistrala). The authorization server(Google) redirects the user back to the client(Magistrala users service) with an authorization code. The client(Magistrala users service) exchanges the authorization code for an access token and a refresh token. The access token is used to authenticate API requests(get user details). The refresh token is used to obtain a new access token when the current access token becomes invalid or expires. This flow is demonstrated in the following diagram:
 
-![authorization code flow](../img/blogs/oauth/codeflow.png)
+![authorization code flow](./codeflow.png)
 _The authorization code flow(from https://medium.com/javarevisited/oauth-2-0-authorization-code-flow-in-spring-boot-d8ff393f316d)_
 
 There are different grant types in OAuth2.0. The grant type is a string representing the authorization grant type that the client is using to request the access token. It is included in the request to the token endpoint. It is used to specify the method of obtaining the access token. It is a required parameter in the request to the token endpoint. The grant types are:
@@ -55,10 +66,10 @@ Currently, we have implemented the OAuth2.0 authorization code flow with Google
 
    ```env
    ### Google OAuth2
-   MG_GOOGLE_CLIENT_ID="01234567-8abc0defg7hijklmnopqr23456s78tu9.apps.googleusercontent.com"
-   MG_GOOGLE_CLIENT_SECRET="GOCSPX-_abCDEfG1hIJKl4MnO7pQRSTuvwxyz"
-   MG_GOOGLE_REDIRECT_URL="http://localhost/oauth/callback/google"
-   MG_GOOGLE_STATE="7NN28jSDAg4z"
+   SMQ_GOOGLE_CLIENT_ID="01234567-8abc0defg7hijklmnopqr23456s78tu9.apps.googleusercontent.com"
+   SMQ_GOOGLE_CLIENT_SECRET="GOCSPX-_abCDEfG1hIJKl4MnO7pQRSTuvwxyz"
+   SMQ_GOOGLE_REDIRECT_URL="http://localhost/oauth/callback/google"
+   SMQ_GOOGLE_STATE="7NN28jSDAg4z"
    ```
 
    The state is a secret key that is shared between the client and the server. It is used to prevent CSRF attacks. The state should be a random string and should be kept secret. The state is used to verify the integrity of the response from the authorization server.

blog/tags.yml

@@ -0,0 +1,84 @@
+facebook:
+  label: Facebook
+  permalink: /facebook
+  description: Facebook tag description
+
+hello:
+  label: Hello
+  permalink: /hello
+  description: Hello tag description
+
+docusaurus:
+  label: Docusaurus
+  permalink: /docusaurus
+  description: Docusaurus tag description
+
+Magistrala:
+  label: Magistrala
+  permalink: /magistrala
+  description: All posts about Magistrala, the open-source IoT platform.
+
+IIoT:
+  label: IIoT
+  permalink: /iiot
+  description: Posts focusing on Industrial Internet of Things (IIoT) solutions and use cases.
+
+User Guide:
+  label: User Guide
+  permalink: /user-guide
+  description: Posts that serve as guides for using Magistrala.
+
+Industrial Automation:
+  label: Industrial Automation
+  permalink: /industrial-automation
+  description: Content related to automating industrial processes with Magistrala.
+
+Open Source:
+  label: Open Source
+  permalink: /open-source
+  description: Insights and updates on Magistrala as an open-source platform.
+
+OAuth2.0:
+  label: OAuth2.0
+  permalink: /oauth2
+  description: Posts about integrating OAuth2.0 with Magistrala for secure authentication.
+
+Authentication:
+  label: Authentication
+  permalink: /authentication
+  description: Content exploring authentication mechanisms like OAuth2.0.
+
+Google OAuth:
+  label: Google OAuth
+  permalink: /google-oauth
+  description: Posts about integrating Google OAuth with Magistrala.
+
+Kratos:
+  label: Kratos
+  permalink: /kratos
+  description: Posts about using Ory Kratos for user management in Magistrala.
+
+User Management:
+  label: User Management
+  permalink: /user-management
+  description: Posts focused on managing users within Magistrala.
+
+Identity:
+  label: Identity
+  permalink: /identity
+  description: Content about identity management and integration in Magistrala.
+
+release:
+  label: Release
+  permalink: /release
+  description: Updates and announcements about new releases of Magistrala.
+
+SuperMQ:
+  label: SuperMQ
+  permalink: /supermq
+  description: Posts related to SuperMQ, a scalable and secure IoT platform.
+
+update:
+  label: Update
+  permalink: /update
+  description: Blog posts about updates and changes to Magistrala.

docs/blogs/user-guide.md → blog/user-guide.md

@@ -1,7 +1,17 @@
-# Magistrala: Revolutionizing Industrial IoT with an Open Source Platform
+---
+slug: magistrala-user-guide
+title: Revolutionizing Industrial IoT with an Open Source Platform
+authors: osodo
+description: Learn how Magistrala simplifies Industrial IoT with robust features like multi-protocol support, scalable architecture, and enhanced security.
+tags: ['Magistrala', 'IIoT', 'User Guide', 'Industrial Automation', 'Open Source']
+---
+
+## Magistrala: Revolutionizing Industrial IoT with an Open Source Platform
 
 In the world of Industrial Internet of Things (IIoT), businesses are always on the lookout for reliable, scalable, and secure ways to handle their connected devices and data. That's where Magistrala comes in—an open-source IIoT platform that's transforming the way we approach industrial automation and remote monitoring.
 
+<!-- truncate -->
+
 ## Key Advantages of Magistrala
 
 1. **Protocol Flexibility**: Magistrala's support for multiple protocols ensures that devices with different communication methods can easily connect and interact within the same ecosystem.
@@ -247,7 +257,7 @@ This connects the previously created thing to the channel. $THINGID and $CHANNEL
 magistrala-cli messages send $CHANNELID '[{"bn": "DS-5000-AL1-001", "n": "Distance_AssemblyLine1", "u": "mm","v": 152.3}, { "n": "BatteryLevel", "u": "%", "v": 95}, { "n": "SignalStrength", "u": "dBm", "v": -65}]' <thing_secret>
 ```
 
-This sends a message to the specified channel. The message contains temperature and humidity readings. Replace <thing_secret> with the secret of the thing.
+This sends a message to the specified channel. The message contains temperature and humidity readings. Replace thing_secret with the secret of the thing.
 
 **Note:** The secret for the thing can be specified during its creation. If not provided, it will be automatically generated by the platform. To view the generated secret, please access the thing's profile as follows: