diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 143a3a2..8442293 100644 --- 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/CONTRIBUTING.md b/CONTRIBUTING.md index 45b8724..e0b9198 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -53,11 +53,11 @@ git checkout main git pull --rebase upstream main ``` -Create a new topic branch from `main` 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 @@ -80,7 +80,7 @@ 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/blog/oauth/oauth.md b/blog/oauth/oauth.md index 5e4b8bb..c34ae8a 100644 --- a/blog/oauth/oauth.md +++ b/blog/oauth/oauth.md @@ -66,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. diff --git a/docs/authentication.md b/docs/authentication.md index b3f8e8e..446d290 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -25,22 +25,22 @@ The following actions are supported: Federated authentication is a process of authenticating users using external identity providers. SuperMQ supports federated authentication using [OpenID Connect][oidc] protocol. SuperMQ is a resource provider and it uses [Google Identity Platform][google-identity-platform] as an identity provider. To use federated authentication, you need to create a project in Google Cloud Platform and enable Google Identity Platform API. After that, you need to create OAuth 2.0 credentials and configure the consent screen. This can be done by following Google's [documentation][google-identity-platform-docs]. Once you have created OAuth 2.0 credentials, you need to set the following environment variables: ```bash -MG_USERS_GOOGLE_CLIENT_ID=985229335584-m2mft8lqbgfn5gfw9ftrm3r2sgu4tsrw.apps.googleusercontent.com -MG_USERS_GOOGLE_CLIENT_SECRET=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YUIpw -MG_UI_GOOGLE_REDIRECT_URL=http://localhost/google-callback -MG_USERS_GOOGLE_STATE=pGXVNhEeKfycuBzk5InlSfMlEU9UrhlkTUOSqhsgDzXP2Y4RsN -MG_USERS_UI_REDIRECT_URL=http://localhost:9090 +SMQ_USERS_GOOGLE_CLIENT_ID=985229335584-m2mft8lqbgfn5gfw9ftrm3r2sgu4tsrw.apps.googleusercontent.com +SMQ_USERS_GOOGLE_CLIENT_SECRET=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YUIpw +SMQ_UI_GOOGLE_REDIRECT_URL=http://localhost/google-callback +SMQ_USERS_GOOGLE_STATE=pGXVNhEeKfycuBzk5InlSfMlEU9UrhlkTUOSqhsgDzXP2Y4RsN +SMQ_USERS_UI_REDIRECT_URL=http://localhost:9090 ``` -1. `MG_USERS_GOOGLE_CLIENT_ID` - Google OAuth 2.0 client ID -2. `MG_USERS_GOOGLE_CLIENT_SECRET` - Google OAuth 2.0 client secret -3. `MG_UI_GOOGLE_REDIRECT_URL` - Google OAuth 2.0 redirect URL to handle callback after successful authentication. This URL must be registered in the Google Cloud Platform. -4. `MG_USERS_GOOGLE_STATE` - Random string used to protect against cross-site request forgery attacks. -5. `MG_USERS_UI_REDIRECT_URL` - URL to redirect user after successful authentication. This can be your SuperMQ UI URL. +1. `SMQ_USERS_GOOGLE_CLIENT_ID` - Google OAuth 2.0 client ID +2. `SMQ_USERS_GOOGLE_CLIENT_SECRET` - Google OAuth 2.0 client secret +3. `SMQ_UI_GOOGLE_REDIRECT_URL` - Google OAuth 2.0 redirect URL to handle callback after successful authentication. This URL must be registered in the Google Cloud Platform. +4. `SMQ_USERS_GOOGLE_STATE` - Random string used to protect against cross-site request forgery attacks. +5. `SMQ_USERS_UI_REDIRECT_URL` - URL to redirect user after successful authentication. This can be your SuperMQ UI URL. SuperMQ handles the authentication callback at `/google-callback` endpoint, where `` is the base URL of your SuperMQ instance. This endpoint needs to be registered in the Google Cloud Platform and it must match the value of `MG_UI_GOOGLE_REDIRECT_URL` environment variable. If an error occurs, the error message is sent from the backend using a query paramters with the key `error`. The UI will read the error message from the query parameter and display it to the user. When a user signs up, SuperMQ creates a local copy of the user with an ID provided by Google, the name and email address provided by Google and the password is left empty as the user is authenticated using Google, i.e. external user. The user can be created only once, so if the user already exists, the error will be sent to the UI via the error cookie. Finally, the user is redirected to the URL provided in `MG_USERS_UI_REDIRECT_URL` environment variable upon successful authentication. This should be the base URL of your UI. -The `MG_USERS_GOOGLE_CLIENT_ID`, `MG_USERS_GOOGLE_CLIENT_SECRET`, `MG_UI_GOOGLE_REDIRECT_URL` and `MG_USERS_GOOGLE_STATE` environment variables should be the same for the UI and users service. The `MG_USERS_UI_REDIRECT_URL` environment variable should be the URL of your UI which is used to redirect the user after successful authentication. +The `SMQ_USERS_GOOGLE_CLIENT_ID`, `SMQ_USERS_GOOGLE_CLIENT_SECRET`, `SMQ_UI_GOOGLE_REDIRECT_URL` and `SMQ_USERS_GOOGLE_STATE` environment variables should be the same for the UI and users service. The `SMQ_USERS_UI_REDIRECT_URL` environment variable should be the URL of your UI which is used to redirect the user after successful authentication. SuperMQ uses the `access_token` provided by Google only to fetch user information which includes user id, name, given name, family name, picture and locale. The `access_token` is not stored in the database and it's not used for any other purpose. The `id_token` is not used as it presents challenges on refreshing it, thus SuperMQ issues its own `access_token` and `refresh_token` stored in the HTTP-only cookie and it's used to authenticate the user in the subsequent requests. diff --git a/docs/authorization.md b/docs/authorization.md index 0fc3fcf..12b715e 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -771,5 +771,5 @@ There are two ways to user get registered to SuperMQ, self-register and register User registration is self register default which can be changed by following environment variable: ```env -MG_USERS_ALLOW_SELF_REGISTER=true +SMQ_USERS_ALLOW_SELF_REGISTER=true ``` diff --git a/docs/bootstrap.md b/docs/bootstrap.md index bd10c9f..9be6cee 100644 --- a/docs/bootstrap.md +++ b/docs/bootstrap.md @@ -126,7 +126,7 @@ In order to disconnect, the same request should be sent with the value of `state - *Encrypt the external key.* -First, encrypt the external key of your thing using AES encryption. The encryption key is specified by the `MG_BOOTSTRAP_ENCRYPT_KEY` environment variable. Use a library or utility that supports AES encryption to do this. Here's an example of how to encrypt using Go: +First, encrypt the external key of your thing using AES encryption. The encryption key is specified by the `SMQ_BOOTSTRAP_ENCRYPT_KEY` environment variable. Use a library or utility that supports AES encryption to do this. Here's an example of how to encrypt using Go: ```go package main @@ -175,7 +175,7 @@ func main() { } ``` -Replace `` and `` with the thing's external key and `MG_BOOTSTRAP_ENCRYPT_KEY` respectively. +Replace `` and `` with the thing's external key and `SMQ_BOOTSTRAP_ENCRYPT_KEY` respectively. - *Make a request to the bootstrap service.* diff --git a/docs/certs.md b/docs/certs.md index f97dfa1..5326c9b 100644 --- a/docs/certs.md +++ b/docs/certs.md @@ -16,7 +16,7 @@ Certificate service can create certificates in PKI mode - where certificates iss ### PKI mode -When `MG_CERTS_VAULT_HOST` is set, it is presumed that `Vault` is installed and `certs` service will issue certificates using `Vault` API. +When `SMQ_CERTS_VAULT_HOST` is set, it is presumed that `Vault` is installed and `certs` service will issue certificates using `Vault` API. First you'll need to set up `Vault`. @@ -25,10 +25,10 @@ To setup `Vault` follow steps in [Build Your Own Certificate Authority (CA)][vau To setup certs service with `Vault` following environment variables must be set: ```bash -MG_CERTS_VAULT_HOST=vault-domain.com -MG_CERTS_VAULT_PKI_PATH= -MG_CERTS_VAULT_ROLE= -MG_CERTS_VAULT_TOKEN= +SMQ_CERTS_VAULT_HOST=vault-domain.com +SMQ_CERTS_VAULT_PKI_PATH= +SMQ_CERTS_VAULT_ROLE= +SMQ_CERTS_VAULT_TOKEN= ``` For lab purposes you can use docker-compose and script for setting up PKI in [meodor-vault][meodor-vault]. diff --git a/docs/dev-guide.md b/docs/dev-guide.md index bcb87e4..61622f4 100644 --- a/docs/dev-guide.md +++ b/docs/dev-guide.md @@ -235,11 +235,11 @@ nats-server ``` If you want to change the default message broker to [RabbitMQ][rabbitmq], [VerneMQ][vernemq] or [Kafka][kafka] you need to install it on the local system. -To run using a different broker you need to set the `MG_BROKER_TYPE` env variable to `nats`, `rabbitmq` or `vernemq` during make and run process. +To run using a different broker you need to set the `SMQ_BROKER_TYPE` env variable to `nats`, `rabbitmq` or `vernemq` during make and run process. ```bash -MG_BROKER_TYPE= make -MG_BROKER_TYPE= make run +SMQ_BROKER_TYPE= make +SMQ_BROKER_TYPE= make run ``` #### PostgreSQL diff --git a/docs/lora.md b/docs/lora.md index 0bf50e1..9258ca6 100644 --- a/docs/lora.md +++ b/docs/lora.md @@ -22,7 +22,7 @@ Once everything is installed, execute the following command from the LoRa Server docker-compose up ``` -**Troubleshouting:** SuperMQ and LoRa Server use their own MQTT brokers which by default occupy MQTT port `1883`. If both are ran on the same machine different ports must be used. You can fix this on SuperMQ side by configuring the environment variable `MG_MQTT_ADAPTER_MQTT_PORT`. +**Troubleshouting:** SuperMQ and LoRa Server use their own MQTT brokers which by default occupy MQTT port `1883`. If both are ran on the same machine different ports must be used. You can fix this on SuperMQ side by configuring the environment variable `SMQ_MQTT_ADAPTER_MQTT_PORT`. ## Setup LoRa Server @@ -46,9 +46,9 @@ Once everything is running and the LoRa Server is provisioned, execute the follo docker-compose -f docker/addons/lora-adapter/docker-compose.yml up -d ``` -**Troubleshouting:** The lora-adapter subscribes to the LoRa Server MQTT broker and will fail if the connection is not established. You must ensure that the environment variable `MG_LORA_ADAPTER_MESSAGES_URL` is propertly configured. +**Troubleshouting:** The lora-adapter subscribes to the LoRa Server MQTT broker and will fail if the connection is not established. You must ensure that the environment variable `SMQ_LORA_ADAPTER_MESSAGES_URL` is propertly configured. -**Remark:** By defaut, `MG_LORA_ADAPTER_MESSAGES_URL` is set as `tcp://lora.mqtt.supermq.io:1883` in the [docker-compose.yml][lora-docker-compose] file of the adapter. If you run the composition without configure this variable you will start to receive messages from our demo server. +**Remark:** By defaut, `SMQ_LORA_ADAPTER_MESSAGES_URL` is set as `tcp://lora.mqtt.supermq.io:1883` in the [docker-compose.yml][lora-docker-compose] file of the adapter. If you run the composition without configure this variable you will start to receive messages from our demo server. ### Route Map @@ -87,10 +87,10 @@ The lora-adapter uses the matadata of provision events emitted by SuperMQ system To forward LoRa messages the lora-adapter subscribes to topics `applications/+/devices/+` of the LoRa Server MQTT broker. It verifies the `app_id` and the `dev_eui` of received messages. If the mapping exists it uses corresponding `Channel ID` and `Thing ID` to sign and forwards the content of the LoRa message to the SuperMQ message broker. -[lora-adapter]: https://github.com/absmach/supermq/tree/main/lora +[lora-adapter]: https://github.com/absmach/smq-contrib/tree/main/lora [lora-server]: https://www.loraserver.io [lora-gateway]: https://www.loraserver.io/lora-gateway-bridge/overview/ [semtech]: https://github.com/Lora-net/packet_forwarder/blob/master/PROTOCOL.TXT [lora-app-server]: https://www.loraserver.io/lora-app-server/overview/ -[lora-docker-compose]: https://github.com/absmach/supermq/blob/main/docker/addons/lora-adapter/docker-compose.yml +[lora-docker-compose]: https://github.com/absmach/smq-contrib/blob/main/docker/lora-adapter/docker-compose.yml [redis]: https://redis.io/ diff --git a/docs/messaging.md b/docs/messaging.md index 19c29d4..5ce3d02 100644 --- a/docs/messaging.md +++ b/docs/messaging.md @@ -300,13 +300,13 @@ Each broker has a unique profile for configuration. The available profiles are: The following command will run VerneMQ as an MQTT broker and Nats as a message broker: ```bash -MG_MQTT_BROKER_TYPE=vernemq MG_BROKER_TYPE=nats make run +SMQ_MQTT_BROKER_TYPE=vernemq SMQ_BROKER_TYPE=nats make run ``` The following command will run NATS as an MQTT broker and RabbitMQ as a message broker: ```bash -MG_MQTT_BROKER_TYPE=nats MG_BROKER_TYPE=rabbitmq make run +SMQ_MQTT_BROKER_TYPE=nats SMQ_BROKER_TYPE=rabbitmq make run ``` By default, NATS is used as an MQTT broker and RabbitMQ as a message broker. @@ -358,26 +358,26 @@ SuperMQ supports [NATS][nats], [RabbitMQ][rabbitmq] and [Kafka][kafka] as messag ### NATS JetStream -Since SuperMQ supports configurable message brokers, you can use Nats with JetStream enabled as a message broker. To do so, you need to set `MG_BROKER_TYPE` to `nats` and set `MG_NATS_URL` to the url of your nats instance. When using `make` command to start SuperMQ `MG_BROKER_URL` is automatically set to `MG_NATS_URL`. +Since SuperMQ supports configurable message brokers, you can use Nats with JetStream enabled as a message broker. To do so, you need to set `SMQ_BROKER_TYPE` to `nats` and set `SMQ_NATS_URL` to the url of your nats instance. When using `make` command to start SuperMQ `SMQ_BROKER_URL` is automatically set to `SMQ_NATS_URL`. Since SuperMQ is using `nats:2.9.21-alpine` docker image with the following configuration: ```conf max_payload: 1MB max_connections: 1M -port: $MG_NATS_PORT -http_port: $MG_NATS_HTTP_PORT +port: $SMQ_NATS_PORT +http_port: $SMQ_NATS_HTTP_PORT trace: true jetstream { store_dir: "/data" cipher: "aes" - key: $MG_NATS_JETSTREAM_KEY + key: $SMQ_NATS_JETSTREAM_KEY max_mem: 1G } ``` -These are the default values but you can change them by editing the configuration file. For more information about nats configuration checkout [official nats documentation][nats-jestream]. The health check endpoint is exposed on `MG_NATS_HTTP_PORT` and its `/healthz` path. +These are the default values but you can change them by editing the configuration file. For more information about nats configuration checkout [official nats documentation][nats-jestream]. The health check endpoint is exposed on `SMQ_NATS_HTTP_PORT` and its `/healthz` path. #### Architecture @@ -387,9 +387,9 @@ This versatile architecture allows you to use nats alone for the MQTT broker, me ### RabbitMQ -Since SuperMQ uses a configurable message broker, you can use RabbitMQ as a message broker. To do so, you need to set `MG_BROKER_TYPE` to `rabbitmq` and set `MG_RABBITMQ_URL` to the url of your RabbitMQ instance. When using `make` command to start SuperMQ `MG_BROKER_URL` is automatically set to `MG_RABBITMQ_URL`. +Since SuperMQ uses a configurable message broker, you can use RabbitMQ as a message broker. To do so, you need to set `SMQ_BROKER_TYPE` to `rabbitmq` and set `SMQ_RABBITMQ_URL` to the url of your RabbitMQ instance. When using `make` command to start SuperMQ `SMQ_BROKER_URL` is automatically set to `SMQ_RABBITMQ_URL`. -Since SuperMQ is using `rabbitmq:3.9.20-management-alpine` docker image, the management console is available at port `MG_RABBITMQ_HTTP_PORT` +Since SuperMQ is using `rabbitmq:3.9.20-management-alpine` docker image, the management console is available at port `SMQ_RABBITMQ_HTTP_PORT` #### Architecture @@ -412,7 +412,7 @@ For more information and examples checkout [official nats.io documentation][nats ### Kafka -Since SuperMQ uses a configurable message broker, you can use Kafka as a message broker. To do so, you need to set `MG_BROKER_TYPE` to `kafka` and set `MG_KAFKA_URL` to the url of your Kafka instance. When using `make` command to start SuperMQ `MG_BROKER_URL` is automatically set to `MG_KAFKA_URL`. +Since SuperMQ uses a configurable message broker, you can use Kafka as a message broker. To do so, you need to set `SMQ_BROKER_TYPE` to `kafka` and set `SMQ_KAFKA_URL` to the url of your Kafka instance. When using `make` command to start SuperMQ `SMQ_BROKER_URL` is automatically set to `SMQ_KAFKA_URL`. SuperMQ utilizes `spotify/kafka:latest` docker image. The image also exposes `kafka:9092` and `zookeeper:2181` ports. This is used for development purposes only. For production, it is assumed that you have your own Kafka cluster. diff --git a/docs/opcua.md b/docs/opcua.md index bba64b4..3d59666 100644 --- a/docs/opcua.md +++ b/docs/opcua.md @@ -117,7 +117,7 @@ The OPC-UA adapter can be used in an industrial setup to monitor process values Things on SuperMQ can be created to represent these devices and the channels can be created to represent the data points on the devices. The OPC-UA adapter can then be used to subscribe to the OPC-UA server and forward the data to the NATS message broker. This data can then be consumed by other services in the SuperMQ system, and further processing done if need be. -[opcua-adapter]: https://github.com/absmach/supermq/tree/main/opcua +[opcua-adapter]: https://github.com/absmach/smq-contrib/tree/main/opcua [opcua-arch]: https://en.wikipedia.org/wiki/OPC_Unified_Architecture [public-opcua]: https://github.com/node-opcua/node-opcua/wiki/publicly-available-OPC-UA-Servers-and-Clients [redis]: https://redis.io/ diff --git a/docs/provision.md b/docs/provision.md index e28506d..fc541cf 100644 --- a/docs/provision.md +++ b/docs/provision.md @@ -656,8 +656,8 @@ To provide authentication credentials to the provision service you can pass it i Additionally, users or API token can be passed in Authorization header, this authentication takes precedence over others. -- `username`, `password` - (`MG_PROVISION_USER`, `MG_PROVISION_PASSWORD` in [.env][env], `MG_user`, `MG_pass` in [config.toml][conftoml] -- API Key - (`MG_PROVISION_API_KEY` in [.env][env] or [config.toml][conftoml] +- `username`, `password` - (`SMQ_PROVISION_USER`, `SMQ_PROVISION_PASSWORD` in [.env][env], `SMQ_user`, `SMQ_pass` in [config.toml][conftoml] +- API Key - (`SMQ_PROVISION_API_KEY` in [.env][env] or [config.toml][conftoml] - `Authorization: Bearer Token|ApiKey` - request authorization header containing users token. Check [auth][auth]. ### Running @@ -667,10 +667,10 @@ Provision service can be run as a standalone or in docker composition as addon t Standalone: ```bash -MG_PROVISION_BS_SVC_URL=http://localhost:9013/things \ -MG_PROVISION_THINGS_LOCATION=http://localhost:9000 \ -MG_PROVISION_USERS_LOCATION=http://localhost:9002 \ -MG_PROVISION_CONFIG_FILE=docker/addons/provision/configs/config.toml \ +SMQ_PROVISION_BS_SVC_URL=http://localhost:9013/things \ +SMQ_PROVISION_THINGS_LOCATION=http://localhost:9000 \ +SMQ_PROVISION_USERS_LOCATION=http://localhost:9002 \ +SMQ_PROVISION_CONFIG_FILE=docker/addons/provision/configs/config.toml \ build/supermq-provision ``` @@ -795,9 +795,8 @@ For more information about the Provision service API, please check out the [API [supermq]: https://github.com/absmach/supermq [bootstrap]: https://github.com/absmach/supermq/tree/main/bootstrap [agent]: https://github.com/absmach/agent -[mgui]: https://github.com/absmach/magistrala-ui [config]: https://github.com/absmach/supermq/tree/main/provision#configuration -[env]: https://github.com/absmach/supermq/blob/main/.env +[env]: https://github.com/absmach/supermq/blob/main/docker/.env [conftoml]: https://github.com/absmach/supermq/blob/main/docker/addons/provision/configs/config.toml [users]: https://github.com/absmach/supermq/blob/main/users/README.md [exp]: https://github.com/absmach/export diff --git a/docs/security.md b/docs/security.md index c6bbf81..30bc1e3 100644 --- a/docs/security.md +++ b/docs/security.md @@ -10,22 +10,22 @@ sidebar_position: 9 If either the cert or key is not set, the server will use insecure transport. -`MG_USERS_SERVER_CERT` the path to server certificate in pem format. +`SMQ_USERS_SERVER_CERT` the path to server certificate in pem format. -`MG_USERS_SERVER_KEY` the path to the server key in pem format. +`SMQ_USERS_SERVER_KEY` the path to the server key in pem format. ### Things If either the cert or key is not set, the server will use insecure transport. -`MG_THINGS_SERVER_CERT` the path to server certificate in pem format. +`SMQ_THINGS_SERVER_CERT` the path to server certificate in pem format. -`MG_THINGS_SERVER_KEY` the path to the server key in pem format. +`SMQ_THINGS_SERVER_KEY` the path to the server key in pem format. ### Standalone mode Sometimes it makes sense to run Things as a standalone service to reduce network traffic or simplify deployment. This means that Things service operates only using a single user and is able to authorize it without gRPC communication with Auth service. When running Things in the standalone mode, `Auth` and `Users` services can be omitted from the deployment. -To run service in a standalone mode, set `MG_THINGS_STANDALONE_EMAIL` and `MG_THINGS_STANDALONE_TOKEN`. +To run service in a standalone mode, set `SMQ_THINGS_STANDALONE_EMAIL` and `SMQ_THINGS_STANDALONE_TOKEN`. ## Client Configuration @@ -33,26 +33,26 @@ If you wish to secure the gRPC connection to `Things` and `Users` services you m ### Adapter Configuration -`MG_HTTP_ADAPTER_CA_CERTS`, `MG_MQTT_ADAPTER_CA_CERTS`, `MG_WS_ADAPTER_CA_CERTS`, `MG_COAP_ADAPTER_CA_CERTS` - the path to a file that contains the CAs in PEM format. If not set, the default connection will be insecure. If it fails to read the file, the adapter will fail to start up. +`SMQ_HTTP_ADAPTER_CA_CERTS`, `SMQ_MQTT_ADAPTER_CA_CERTS`, `SMQ_WS_ADAPTER_CA_CERTS`, `SMQ_COAP_ADAPTER_CA_CERTS` - the path to a file that contains the CAs in PEM format. If not set, the default connection will be insecure. If it fails to read the file, the adapter will fail to start up. ### Things Configuration -`MG_THINGS_CA_CERTS` - the path to a file that contains the CAs in PEM format. If not set, the default connection will be insecure. If it fails to read the file, the service will fail to start up. +`SMQ_THINGS_CA_CERTS` - the path to a file that contains the CAs in PEM format. If not set, the default connection will be insecure. If it fails to read the file, the service will fail to start up. ## Securing PostgreSQL Connections By default, SuperMQ will connect to Postgres using insecure transport. If a secured connection is required, you can select the SSL mode and set paths to any extra certificates and keys needed. -`MG_USERS_DB_SSL_MODE` the SSL connection mode for Users. -`MG_USERS_DB_SSL_CERT` the path to the certificate file for Users. -`MG_USERS_DB_SSL_KEY` the path to the key file for Users. -`MG_USERS_DB_SSL_ROOT_CERT` the path to the root certificate file for Users. +`SMQ_USERS_DB_SSL_MODE` the SSL connection mode for Users. +`SMQ_USERS_DB_SSL_CERT` the path to the certificate file for Users. +`SMQ_USERS_DB_SSL_KEY` the path to the key file for Users. +`SMQ_USERS_DB_SSL_ROOT_CERT` the path to the root certificate file for Users. -`MG_THINGS_DB_SSL_MODE` the SSL connection mode for Things. -`MG_THINGS_DB_SSL_CERT` the path to the certificate file for Things. -`MG_THINGS_DB_SSL_KEY` the path to the key file for Things. -`MG_THINGS_DB_SSL_ROOT_CERT` the path to the root certificate file for Things. +`SMQ_THINGS_DB_SSL_MODE` the SSL connection mode for Things. +`SMQ_THINGS_DB_SSL_CERT` the path to the certificate file for Things. +`SMQ_THINGS_DB_SSL_KEY` the path to the key file for Things. +`SMQ_THINGS_DB_SSL_ROOT_CERT` the path to the root certificate file for Things. Supported database connection modes are: `disabled` (default), `required`, `verify-ca` and `verify-full`. diff --git a/docs/smq-contrib.md b/docs/smq-contrib.md new file mode 100644 index 0000000..a63a99a --- /dev/null +++ b/docs/smq-contrib.md @@ -0,0 +1,82 @@ +--- +sidebar_position: 24 +--- + +# SMQ-Contrib Repository + +The **SuperMQ-Contrib** repository serves as a collection of additional services, tools, and extensions that complement the SuperMQ platform. +These contributions include features that did not make it into the main SuperMQ platform but are invaluable for specific use cases. +The repository acts as a playground for exploring and testing new ideas and contributions to the ecosystem. + +This repository is an excellent starting point for developers looking to contribute new features or experiment with custom services and integrations for SuperMQ. + +## Available Services in smq-contrib + +### LoRa +The **[LoRa Adapter][lora]** bridges SuperMQ with LoRaWAN networks. +It forwards messages between SuperMQ and a LoRaWAN Server using MQTT while adhering to JSON and SenML formats. +This adapter is ideal for users integrating low-power, wide-area devices into the SuperMQ ecosystem. + +- [Learn more about the LoRa Adapter](./lora.md) + +--- + +### OPC-UA +The **[OPC-UA Adapter][opcua]** serves as a bridge between SuperMQ and OPC-UA servers, enabling seamless communication with industrial devices. +It supports browse and subscription methods for retrieving data from nodes on the OPC-UA server and forwards this data to the SuperMQ platform. + +- [Learn more about the OPC-UA Adapter](./opcua.md) + +--- + +### Twins Service +The **[Twins Service][twins]** introduces the concept of digital twins to SuperMQ. +Digital twins provide a unified, abstract representation of complex real-world systems. +The Twins Service maintains a history of system states, definitions, and metadata, offering an enhanced way to monitor and manage interconnected devices. + +- [Learn more about the Twins Service](./twins.md) + +--- + +### Readers + +The **[Readers Service][readers]** is designed to persist SuperMQ messages into various databases, providing robust storage options for IoT data. Currently, the following readers are available: + +- **[Cassandra Reader][cassandra]**: Integrates with Apache Cassandra to store and query large volumes of IoT data in a distributed, highly available manner. +- **[InfluxDB Reader][influx]**: Connects with InfluxDB for efficient time-series data storage and real-time queries. +- **[MongoDB Reader][mongodb]**: Leverages MongoDB for storing structured and semi-structured IoT data with powerful query capabilities. + +These readers are implemented as independent services, each designed to interface with the respective database while maintaining compatibility with the SuperMQ messaging infrastructure. + +- [Learn more about the Readers Service](./messaging.md) + +--- + +### Consumers + +**[Consumers][consumers]** work as specialized services that extract messages from the SuperMQ platform and act upon them, helping integrate SuperMQ with broader data-processing workflows. + +--- + +## Contribute to smq-contrib + +The **SuperMQ-Contrib** repository is a dynamic and collaborative space for developers. If you have an idea for an additional service or integration, this is the perfect place to start. + +- **Add your own contributions**: Developers are encouraged to fork the repository, experiment with ideas, and submit pull requests for review. +- **Collaborate with the community**: Join the discussion and help improve existing contributions. + +Visit the [SuperMQ-Contrib GitHub Repository](https://github.com/absmach/smq-contrib) to get started! + +## Conclusion + +The **SuperMQ-Contrib** repository complements the SuperMQ platform by extending its functionality and fostering innovation. Whether you are a contributor or an end-user, the tools and services in this repository enable you to enhance your IoT infrastructure and explore advanced use cases. + +[lora]: https://github.com/absmach/smq-contrib/tree/main/lora +[opcua]: https://github.com/absmach/smq-contrib/tree/main/opcua +[twins]: https://github.com/absmach/smq-contrib/tree/main/twins +[mongodb]: https://github.com/absmach/smq-contrib/tree/main/readers/mongodb +[cassandra]: https://github.com/absmach/smq-contrib/tree/main/readers/cassandra +[influx]: https://github.com/absmach/smq-contrib/tree/main/readers/influxdb +[readers]: https://github.com/absmach/smq-contrib/tree/main/readers +[consumers]: https://github.com/absmach/smq-contrib/tree/main/consumers + diff --git a/docs/storage.md b/docs/storage.md index edea6b0..a822201 100644 --- a/docs/storage.md +++ b/docs/storage.md @@ -20,7 +20,7 @@ In order to run these services, core services, as well as the network from the c ## Writers -Writers provide an implementation of various `message writers`. Message writers are services that consume SuperMQ messages, transform them to desired format and store them in specific data store. The path of the configuration file can be set using the following environment variables: `MG_CASSANDRA_WRITER_CONFIG_PATH`, `MG_POSTGRES_WRITER_CONFIG_PATH`, `MG_INFLUX_WRITER_CONFIG_PATH`, `MG_MONGO_WRITER_CONFIG_PATH` and `MG_TIMESCALE_WRITER_CONFIG_PATH`. +Writers provide an implementation of various `message writers`. Message writers are services that consume SuperMQ messages, transform them to desired format and store them in specific data store. The path of the configuration file can be set using the following environment variables: `SMQ_CASSANDRA_WRITER_CONFIG_PATH`, `SMQ_POSTGRES_WRITER_CONFIG_PATH`, `SMQ_INFLUX_WRITER_CONFIG_PATH`, `SMQ_MONGO_WRITER_CONFIG_PATH` and `SMQ_TIMESCALE_WRITER_CONFIG_PATH`. ### Subscriber config @@ -255,4 +255,4 @@ docker-compose -f docker/addons/timescale-reader/docker-compose.yml up -d [nats-wildcards]: https://docs.nats.io/nats-concepts/subjects#wildcards [writers]: ./storage.md#writers [influxdb]: https://docs.influxdata.com/influxdb -[readers-api]: https://github.com/absmach/supermq/blob/main/api/readers.yml +[readers-api]: https://github.com/absmach/supermq/blob/main/api/openapi/readers.yml diff --git a/docs/tracing.md b/docs/tracing.md index 5ff293b..a3aff6c 100644 --- a/docs/tracing.md +++ b/docs/tracing.md @@ -28,11 +28,11 @@ Jaeger uses 5 ports within the SuperMQ framework. These ports can be edited in t | Variable | Description | Default | | ------------------- | ------------------------------------------------- | ----------- | -| MG_JAEGER_PORT | Agent port for compact jaeger.thrift protocol | 6831 | -| MG_JAEGER_FRONTEND | UI port | 16686 | -| MG_JAEGER_COLLECTOR | Collector for jaeger.thrift directly from clients | 14268 | -| MG_JAEGER_CONFIGS | Configuration server | 5778 | -| MG_JAEGER_URL | Jaeger access from within SuperMQ | jaeger:6831 | +| SMQ_JAEGER_PORT | Agent port for compact jaeger.thrift protocol | 6831 | +| SMQ_JAEGER_FRONTEND | UI port | 16686 | +| SMQ_JAEGER_COLLECTOR | Collector for jaeger.thrift directly from clients | 14268 | +| SMQ_JAEGER_CONFIGS | Configuration server | 5778 | +| SMQ_JAEGER_URL | Jaeger access from within SuperMQ | jaeger:6831 | ## Message Tracing diff --git a/docs/twins.md b/docs/twins.md index 6d06a09..6a199ae 100644 --- a/docs/twins.md +++ b/docs/twins.md @@ -4,7 +4,7 @@ sidebar_position: 19 # Twins Service -SuperMQ twins service is built on top of the SuperMQ platform. In order to fully understand what follows, be sure to get acquainted with [overall SuperMQ architecture][architecture]._ +SuperMQ twins service is built on top of the SuperMQ platform. In order to fully understand what follows, be sure to get acquainted with [overall SuperMQ architecture][architecture]. ## What is Digital Twin @@ -312,7 +312,7 @@ Every twin and states related operation publishes notifications _via_ the messag In order to pick up this notifications, you have to create a SuperMQ channel before you start the twins service and inform the twins service about the channel by means of the environment variable, like this: ```bash -export MG_TWINS_CHANNEL_ID=f6894dfe-a7c9-4eef-a614-637ebeea5b4c +export SMQ_TWINS_CHANNEL_ID=f6894dfe-a7c9-4eef-a614-637ebeea5b4c ``` The twins service will use this channel to publish notifications related to twins creation, update, retrieval and deletion. It will also publish notifications related to state saving into the database. @@ -320,7 +320,7 @@ The twins service will use this channel to publish notifications related to twin All notifications will be published on the following message broker subject: ```txt -channels.. +channels.. ``` where `` is one of the following: diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 8b51d08..456b905 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -128,6 +128,9 @@ const config: Config = { theme: prismThemes.github, darkTheme: prismThemes.dracula, }, + typography: { + fontFamily: 'Inter, sans-serif', + }, } satisfies Preset.ThemeConfig, }; diff --git a/src/css/custom.css b/src/css/custom.css index 96c5e42..d1af911 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -1,3 +1,5 @@ +@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap'); + /** * Any CSS included here will be global. The classic template * bundles Infima by default. Infima is a CSS framework designed to @@ -28,3 +30,11 @@ --ifm-color-primary-lightest: #bfdbfe; --docusaurus-highlighted-code-line-bg: rgba(59, 130, 246, 0.3); } + +body, h1, h2, h3, h4, h5, h6, p, li, a, span, code { + font-family: 'Inter', sans-serif; +} + +h1, h2, h3, h4, h5, h6 { + font-weight: 600; +}