diff --git a/docs/aws.md b/docs/aws.md index cd2516a1e..0da4ccc02 100644 --- a/docs/aws.md +++ b/docs/aws.md @@ -12,22 +12,74 @@ This schema represent the various components and how they interact to have a bet 1. The IoT Hub portal uses the AWS S3 storage to store the device models configuration (Images, Commands, etc.). 1. The IoT Hub portal synchronizes its data with the IoT Hub to provide a consistent view of the data. +## Quick Start + +### Prerequisites + +* You must have an AWS Account. Get an [AWS Free account](https://portal.aws.amazon.com/billing/signup#/start/email) to get started. + +### Deployed Resources + +The template will deploy in your AWS Account the Following resources: + +* AWS RDS - Database for PostgreSQL +* AWS S3 Bucket +* AWS App Runner Service + +### Instructions + +1. Choose a stack name for your AWS Deployment. + +1. Follow next step below to start your deployment: + + 1. Press on the button here below to download the template AWS: + [Download the template](https://github.com/CGI-FR/IoT-Hub-Portal/blob/1940-cloudformation-script-creation/templates/aws/awsdeploy.yml) + + 1. Import your template : + ***From the AWS console: [CloudFormation new stack](https://eu-west-1.console.aws.amazon.com/cloudformation/home?region=eu-west-1#/stacks/create)*** + - You can change the deployment region by changing the region directly in the URL + - In "Upload a template file" import the previously downloaded file + ***With AWS CLI:*** + + ```console + aws cloudformation deploy --template /path_to_template/awsdeploy.yml --stack-name your-stack-name --region your-region + ``` + + > see: [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-cli-deploy.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-cli-deploy.html) for more option about aws cloudformation deploy + +1. You will get to a page asking you to fill the following fields: + * **Stack Name**: A name for the stack where all the template resource would be put into, just choose a meaningful name. + * **Unique Solution Prefix**: A string that would be used as prefix for all the resources name to ensure their uniqueness. + * **PostgreSQL user**: The PostgreSQL user name to be used for the IoT Hub Portal database. + * **PostgreSQL password**: The PostgreSQL password to be used for the IoT Hub Portal database. + * **AWS Access Key**: The AWS Access Key of your AWS environment. + * **AWS Access Secret Key**: The AWS Access Secret Key of your AWS environment. + * **Api Client Id**: the ID of the API client that will be used to authenticate the portal. + * **Client Id**: the ID of the web client that will be used to authenticate the portal. + * **Open Id Authority**: The OpenID authority used by the portal. + * **OpenId Metadata URL**: The OpenID metadata URL used by the portal. + * **OpenId Scope Name**: The Open ID Scope name ## Configurations + This configurations are used to get access to AWS cloud Platform. You have to enter them in a `json` file to be able to connect to the Iot Hub Portal. Here is a template of a such `json` file. + ```json { "CloudProvider": "AWS", - "S3Storage:ConnectionString": "", + "AWS:Access": "", + "AWS:AccessSecret": "", + "AWS:Region": "", + "AWS:S3Storage:ConnectionString": "", "OIDC:Scope": "", "OIDC:MetadataUrl": "", "OIDC:ClientId": "", "OIDC:Authority": "", "OIDC:ApiClientId": "", "PostgreSQL:ConnectionString": "", - "AWS:Access": "", - "AWS:AccessSecret": "", - "AWS:Region": "" } ``` -> Note: You must replace all values in the brackets by your own AWS settings. If you can't find them in the AWS Portal, please contact an administrator of this project to have more information. \ No newline at end of file + +> Note: You must replace all values in the brackets by your own AWS settings. If you can't find them in the AWS Portal, please contact an administrator of this project to have more information. + +You are now ready to start your IoT Hub Portal development ! diff --git a/docs/azure.md b/docs/azure.md index eb6662a7d..d677abd7e 100644 --- a/docs/azure.md +++ b/docs/azure.md @@ -18,6 +18,61 @@ This schema represent the various components and how they interact to have a bet > Note: For more information about the LoRa Key Management Facade, see the [Azure IoT Edge LoRaWAN Starter Kit](https://azure.github.io/iotedge-lorawan-starterkit) page. +## Quick Start + +### Prerequisites + +* You must have an Azure subscription. Get an [Azure Free account](https://azure.microsoft.com/en-us/offers/ms-azr-0044p/) to get started. +* You must have configured an Azure AD B2C Tenant with applications. See [Portal AD applications configuration](https://cgi-fr.github.io/IoT-Hub-Portal/stable/b2c-applications) page. +* Understand how IoT Edge LoraWAN StarterKit work. Have a look at [https://azure.github.io/iotedge-lorawan-starterkit](https://azure.github.io/iotedge-lorawan-starterkit) to get started. + +### Deployed Resources + +The template will deploy in your Azure subscription the Following resources: + +* IoT Hub +* Azure Function and Consumption Service Plan +* Redis Cache +* Application Insights +* Log Analytics (when opted in to use Azure Monitor) +* Azure WebApp and Service Plan +* Azure Database for PostgreSQL + +### Instructions + +1. Choose a solution prefix for your Azure Deployment. + +1. Configure your AD to connect to the portal. + Use [Portal AD applications configuration](https://cgi-fr.github.io/IoT-Hub-Portal/stable/b2c-applications) page to configure your AD B2C Tenant : + + > You should have recorded the following information: + > + > * OpenID authority: `` + > * OpenID metadata URL: `` + > * Client ID: `` + > * API Client ID: `` + +1. Press on the button here below to start your deployment on Azure: + [![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FCGI-FR%2FIoT-Hub-Portal%2Farm%2Fmain%2Ftemplates%2Fazuredeploy.json/uiFormDefinitionUri/https%3A%2F%2Fraw.githubusercontent.com%2FCGI-FR%2FIoT-Hub-Portal%2Farm%2Fmain%2Ftemplates%2FazuredeployUI.json) + +1. You will get to a page asking you to fill the following fields: + * **Resource Group**: A logical "folder" where all the template resource would be put into, just choose a meaningful name. + * **Location**: In which DataCenter the resources should be deployed. Make sure to choose a location where IoT Hub is available + * **Unique Solution Prefix**: A string that would be used as prefix for all the resources name to ensure their uniqueness. + * **PostgreSQL user**: The PostgreSQL user name to be used for the IoT Hub Portal database. + * **PostgreSQL password**: The PostgreSQL password to be used for the IoT Hub Portal database. + * **Confirm PostgreSQL password**: The PostgreSQL password to be used for the IoT Hub Portal database. + * **Open Id Authority**: The OpenID authority used by the portal. + * **OpenId Metadata URL**: The OpenID metadata URL used by the portal. + * **Client Id**: the ID of the web client that will be used to authenticate the portal. + * **Api Client Id**: the ID of the API client that will be used to authenticate the portal. + * **Edge gateway name**: the name of your LoRa Gateway node in the IoT Hub. + * **Deploy Device**: Do you want demo end devices to be already provisioned (one using OTAA and one using ABP)? If yes set this to true, the code located in the Arduino folder would be ready to use immediately. + * **Reset pin**: The reset pin of your gateway (the value should be 7 for the Seed Studio LoRaWan, 25 for the IC880A) + * **Region**: In what region are you operating your device (currently only EU868 and US915 is supported) + + > see: [https://azure.github.io/iotedge-lorawan-starterkit/dev/quickstart/#deployed-azure-infrastructure](https://azure.github.io/iotedge-lorawan-starterkit/dev/quickstart/#deployed-azure-infrastructure) for more information about the LoRaWan IoT Hub and Azure deployment. + ## Configurations/Secrets _Secrets_ are used to fill in the login credentials to the cloud platform. You have to enter them in a `json` file to be able to connect to the IoT Hub Portal. Here is a template of a such `json` file : diff --git a/docs/index.md b/docs/index.md index 0327ecd88..a13f920ee 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,9 +1,7 @@ # IoT Hub Portal -This project aims to provide a solution for handling IoT Devices easily. -It leverages on Azure IoT Hub for connectivity and device management. - -![IoT Hub Portal Architecture](images/architecture.png) +This project aims to provide a solution for handling IoT Devices easyly. +It leverages on Azure IoT Hub or AWS IoT Core for connectivity and device management. ## Features @@ -13,64 +11,19 @@ It leverages on Azure IoT Hub for connectivity and device management. * C2D Methods * LoRA WAN device connectivity -## Prerequisites - -The following should be completed before proceeding with the IoT Hub Portal development or deployment in your environment. - -* You must have an Azure subscription. Get an [Azure Free account](https://azure.microsoft.com/en-us/offers/ms-azr-0044p/) to get started. -* You must have configured an Azure AD B2C Tenant with applications. See [Portal AD applications configuration](https://cgi-fr.github.io/IoT-Hub-Portal/stable/b2c-applications) page. -* Understand how IoTEdge LoraWAN StarterKit work. Have a look at [https://azure.github.io/iotedge-lorawan-starterkit](https://azure.github.io/iotedge-lorawan-starterkit) to get started. - ## Quick Start -### Deployed Azure Resources - -The template will deploy in your Azure subscription the Following resources: - -* IoT Hub -* Azure Function and Consumption Service Plan -* Redis Cache -* Application Insights -* Log Analytics (when opted in to use Azure Monitor) -* Azure WebApp and Service Plan -* Azure Database for PostgreSQL - -### Instructions - -1. Choose a solution prefix for your deployment. -1. Use [Portal AD applications configuration](https://cgi-fr.github.io/IoT-Hub-Portal/stable/b2c-applications) page to configure your AD B2C Tenant. - > You should have recorded the following information: - > - > * OpenID authority: `` - > * OpenID metadata URL: `` - > * Client ID: `` - > * API Client ID: `` - -1. Press on the button here below to start your Azure Deployment. +### Azure - [![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FCGI-FR%2FIoT-Hub-Portal%2Fmain%2Ftemplates%2Fazuredeploy.json/uiFormDefinitionUri/https%3A%2F%2Fraw.githubusercontent.com%2FCGI-FR%2FIoT-Hub-Portal%2Fmain%2Ftemplates%2FazuredeployUI.json) +[Quick Start](azure/#quick-start) for Azure environment. -1. You will get to a page asking you to fill the following fields : - * **Resource Group**: A logical "folder" where all the template resource would be put into, just choose a meaningful name. - * **Location**: In which Azure Region the resources should be deployed. Make sure to choose a location where IoT Hub is available - * **Unique Solution Prefix**: A string that would be used as prefix for all the resources name to ensure their uniqueness. - * **PostgreSQL user**: The PostgreSQL user name to be used for the IoT Hub Portal database. - * **PostgreSQL password**: The PostgreSQL password to be used for the IoT Hub Portal database. - * **Confirm PostgreSQL password**: The PostgreSQL password to be used for the IoT Hub Portal database. - * **Open Id Authority**: The OpenID authority used by the portal. - * **OpenId Metadata URL**: The OpenID metadata URL used by the portal. - * **Client Id**: the ID of the web client that will be used to authenticate the portal. - * **Api Client Id**: the ID of the API client that will be used to authenticate the portal. - * **Edge gateway name**: the name of your LoRa Gateway node in the IoT Hub. - * **Deploy Device**: Do you want demo end devices to be already provisioned (one using OTAA and one using ABP)? If yes set this to true, the code located in the Arduino folder would be ready to use immediately. - * **Reset pin**: The reset pin of your gateway (the value should be 7 for the Seed Studio LoRaWan, 25 for the IC880A) - * **Region**: In what region are you operating your device (currently only EU868 and US915 is supported) +### Amazon Web Services - > see: [https://azure.github.io/iotedge-lorawan-starterkit/dev/quickstart/#deployed-azure-infrastructure](https://azure.github.io/iotedge-lorawan-starterkit/dev/quickstart/#deployed-azure-infrastructure) for more information about the LoRaWan IoT Hub and Azure deployment. +[Quick Start](aws/#quick-start) for AWS environment. ## Known Issues and Limitations -Refer to [Known Issues](knownissues) for known issues, gotchas and limitations. +Refer to [Known Issues](https://github.com/CGI-FR/IoT-Hub-Portal/issues) for known issues, gotchas and limitations. ## Support diff --git a/mkdocs.yml b/mkdocs.yml index 67b00ee38..8f81c61dd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -110,8 +110,8 @@ extra: # Navigation nav: - index.md - - AWS: 'aws.md' - Azure: 'azure.md' + - AWS: 'aws.md' - Dev Guide: - 'Developer Guide': 'dev-guide.md' - 'Testing':