Merge pull request #205 from Musilah/renameSuperMQ

* rename magistrala to supermq Signed-off-by: Musilah <[email protected]> * add deployment changes Signed-off-by: Musilah <[email protected]> * fix CI Signed-off-by: Musilah <[email protected]> * adjust primary blue shade and metadata Signed-off-by: Musilah <[email protected]> * add new light mode logo Signed-off-by: Musilah <[email protected]> * Fix SemVer and delete docusaurus social card Signed-off-by: Musilah <[email protected]> * fix prefixes and add smq contrib file Signed-off-by: Musilah <[email protected]> * fix broken anchors Signed-off-by: Musilah <[email protected]> * change navbar Signed-off-by: Musilah <[email protected]> * reword homepage Signed-off-by: Musilah <[email protected]> * update sidebar Signed-off-by: Musilah <[email protected]> * revert to default green theme Signed-off-by: Musilah <[email protected]> --------- Signed-off-by: Musilah <[email protected]>
absmach · Dec 11, 2024 · 09551be · 09551be
2 parents b3c0e81 + bd872df
commit 09551be
Show file tree

Hide file tree

Showing 85 changed files with 31,465 additions and 769 deletions.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,4 +1,4 @@
-Pull request title should be `MG-XXX - description` or `NOISSUE - description` where XXX is ID of issue that this PR relate to.
+Pull request title should be `SMQ-XXX - description` or `NOISSUE - description` where XXX is ID of issue that this PR relate to.
 Please review the [CONTRIBUTING.md](./CONTRIBUTING.md) file for detailed contributing guidelines.
 
 ### What does this do?

diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -0,0 +1,57 @@
+name: Deploy Docusaurus to GitHub Pages
+
+# Controls when the action will run
+on:
+  push:
+    branches:
+      - main
+
+  workflow_dispatch:
+permissions:
+  contents: write
+
+jobs:
+  build:
+    name: Build Docusaurus
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: yarn
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Build the website
+        run: yarn build
+
+      - name: Upload Build Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build
+
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+
+    permissions:
+      pages: write
+      id-token: write
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+        env:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
diff --git a/.github/workflows/test-deploy.yml b/.github/workflows/test-deploy.yml
@@ -0,0 +1,28 @@
+name: Test deployment
+
+on: 
+    pull_request:
+        branches:
+            - main
+
+jobs:
+    test-deploy:
+        name: Test deployment
+        runs-on: ubuntu-latest
+        steps: 
+            - name: Checkout main
+              uses: actions/checkout@v4
+              with:
+                  fetch-depth: 0
+
+            - name: Set up Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: 18
+                  cache: yarn
+
+            - name: Install dependencies
+              run: yarn install --frozen-lockfile
+
+            - name: Test Build the website
+              run: yarn build
diff --git a/.gitignore b/.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*
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,7 +1,7 @@
-# Contributing to Magistrala
+# Contributing to SuperMQ
 
-The following is a set of guidelines to contribute to Magistrala and its libraries, which are
-hosted on the [Magistrala Organization](https://github.com/absmach/magistrala) on GitHub.
+The following is a set of guidelines to contribute to SuperMQ and its libraries, which are
+hosted on the [SuperMQ Organization](https://github.com/absmach/supermq) on GitHub.
 
 This project adheres to the [Contributor Covenant 1.2](http://contributor-covenant.org/version/1/2/0).
 By participating, you are expected to uphold this code. Please report unacceptable behavior to
@@ -49,15 +49,15 @@ 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:
 
 ```
-git checkout master
-git pull --rebase upstream master
+git checkout main
+git pull --rebase upstream main
 ```
 
-Create a new topic branch from `master` using the naming convention `MG-[issue-number]`
+Create a new topic branch from `main` using the naming convention `SMQ-[issue-number]`
 to help us keep track of your contribution scope:
 
 ```
-git checkout -b MG-[issue-number]
+git checkout -b SMQ-[issue-number]
 ```
 
 Commit your changes in logical chunks. When you are ready to commit, make sure
@@ -74,13 +74,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:
 
 ```
-git pull --rebase upstream master
+git pull --rebase upstream main
 ```
 
 Push your topic branch up to your fork:
 
 ```
-git push origin MG-[issue-number]
+git push origin SMQ-[issue-number]
 ```
 
 [Open a Pull Request](https://help.github.com/articles/using-pull-requests/) with a clear title

diff --git a/README.md b/README.md
@@ -8,35 +8,41 @@ This repo collects the collaborative work on SuperMQ documentation.
 The official documentation is hosted at [SuperMQ Docs page][docs].
 Documentation is auto-generated from Markdown files in this repo.
 
-[MkDocs](https://www.mkdocs.org/) is used to serve the docs locally with different theming.
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
 > Additional practical information about SuperMQ system, news and tutorials can be found on the [SuperMQ blog][blog].
 
 ## Prerequisites
 
-Install [MkDocs](https://www.mkdocs.org/#installation)
+Install [Docusaurus](https://docusaurus.io/docs/installation)
 
-```bash
-pip install mkdocs
-```
+### Installation
 
-## Install
+```
+$ yarn
+```
 
 Doc repo can be fetched from GitHub:
 
 ```bash
 git clone [email protected]:/absmach/supermq-docs.git
 ```
 
-## Usage
+### Local Development
+Use Docusaurus to serve documentation.
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
-Use MkDocs to serve documentation:
+### Build
 
-```bash
-mkdocs serve
+```
+$ yarn build
 ```
 
-Then just point the browser to `http://127.0.0.1:8000`.
 
 ## Contributing
 

diff --git a/blog/authors.yml b/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]'
diff --git a/blog/index.md b/blog/index.md
@@ -0,0 +1,19 @@
+---
+title: Welcome to the SuperMQ Blog
+slug: /
+authors: osodo
+---
+
+
+# Welcome to the SuperMQ Blog
+
+This section contains a list of blogs that are related to SuperMQ. 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 SuperMQ v0.14.0](./v0-14-0-release/v0-14-0-release.md)
+- [Extending SuperMQ Users Repository](./kratos/kratos.md)
+- [Integrating OAuth2.0 with SuperMQ](./oauth/oauth.md)
+- [Guide on using SuperMQ](./user-guide.md)
diff --git a/docs/img/blogs/kratos/architecture.png → blog/kratos/architecture.png b/docs/img/blogs/kratos/architecture.png → blog/kratos/architecture.png
diff --git a/docs/blogs/kratos.md → blog/kratos/kratos.md b/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.
 

diff --git a/docs/img/blogs/oauth/codeflow.png → blog/oauth/codeflow.png b/docs/img/blogs/oauth/codeflow.png → blog/oauth/codeflow.png
diff --git a/docs/img/blogs/oauth/genericflow.png → blog/oauth/genericflow.png b/docs/img/blogs/oauth/genericflow.png → blog/oauth/genericflow.png
diff --git a/docs/blogs/oauth.md → blog/oauth/oauth.md b/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.