GITBOOK-223: No subject

Author: stefan-hudelmaier

.gitbook/assets/image (1) (1).png

@@ -0,0 +1,149 @@
+#!/usr/bin/env python
+import json
+import re
+import subprocess
+import sys
+
+from termcolor import colored
+
+
+def run_command(command):
+    runnable_command = command.split()
+    output = subprocess.check_output(runnable_command).decode("utf-8")
+
+    return output
+
+
+def run_command_with_json_output(command):
+    output = run_command(command)
+    result = json.loads(output)
+
+    return result
+
+
+def print_usage(error=None):
+    if error:
+        print(colored(error, 'red'))
+
+    print(f"""
+{colored('Usage:', 'white')}
+Recommended usage:
+- ./migrate-redis.py https://url-to-source-ux4iot-in-azure-portal.com/ https://url-to-target-ux4iot-in-azure-portal.com/
+
+Alternative usage:
+- ./migrate-redis.py source_subscription_id source_resource_group source_ux4iot_name target_subscription_id target_resource_group target_ux4iot_name
+""")
+
+
+def parse_ux4iot_args(args):
+    if len(args) == 0:
+        print_usage('Illegal number of parameters')
+        sys.exit(1)
+
+    url_pattern = r'^https?://'  # Regular expression pattern to match the start of a URL
+    source_url = args[0]
+    target_url = args[1]
+
+    if re.match(url_pattern, source_url) and re.match(url_pattern, target_url):
+        # The variable contains a valid URL
+        # Extract the subscription ID
+        source_subscription_id = re.search(
+            r'subscriptions/([^/]+)', source_url).group(1)
+
+        # Extract the resource group
+        source_resource_group = re.search(
+            r'resourceGroups/([^/]+)', source_url).group(1)
+
+        # Extract the service name
+        source_ux4iot_name = re.search(
+            r'applications/([^/]+)', source_url).group(1)
+
+        # The variable contains a valid URL
+        # Extract the subscription ID
+        target_subscription_id = re.search(
+            r'subscriptions/([^/]+)', target_url).group(1)
+
+        # Extract the resource group
+        target_resource_group = re.search(
+            r'resourceGroups/([^/]+)', target_url).group(1)
+
+        # Extract the service name
+        target_ux4iot_name = re.search(
+            r'applications/([^/]+)', target_url).group(1)
+
+    else:
+        # The variable does not contain a valid URL
+        if len(args) < 6:
+            print_usage("Illegal number of parameters")
+            sys.exit(1)
+
+        print(args)
+
+        source_subscription_id = args[0]
+        source_resource_group = args[1]
+        source_ux4iot_name = args[2]
+        target_subscription_id = args[3]
+        target_resource_group = args[4]
+        target_ux4iot_name = args[5]
+
+    return {
+        "source_subscription_id": source_subscription_id,
+        "source_resource_group": source_resource_group,
+        "source_ux4iot_name": source_ux4iot_name,
+        "target_subscription_id": target_subscription_id,
+        "target_resource_group": target_resource_group,
+        "target_ux4iot_name": target_ux4iot_name,
+    }
+
+
+def copy_redis_file_share(source_storage_account, target_storage_account):
+    pass
+
+
+def get_dump_file_url(subscription_id, resource_group, ux4iot_name):
+    managed_app = run_command_with_json_output(
+        f"az managedapp show --subscription {subscription_id} --resource-group {resource_group} --name {ux4iot_name}")
+    managed_resource_group_id = managed_app['managedResourceGroupId']
+    managed_resource_group_resource = run_command_with_json_output(
+        f"az resource show --ids {managed_resource_group_id}")  # | jq -r .name)
+    managed_resource_group_name = managed_resource_group_resource['name']
+    resources = run_command_with_json_output(
+        f"az resource list --resource-group {managed_resource_group_name}")
+    storage_account_name = next(
+        (r['name'] for r in resources if r["type"] == "Microsoft.Storage/storageAccounts"), None)
+
+    print('Getting redisi dump file url')
+    storage_redis_dump_file_url = run_command_with_json_output(
+        f"az storage file url --account-name {storage_account_name} --path dump.rdb --share-name redis")
+
+    print('Getting sas token for redis dump file')
+    sas_token = run_command_with_json_output(
+        f"az storage file generate-sas --account-name {storage_account_name} --start 2023-01-09T00:00:00Z --expiry 2023-12-31T23:59:00Z --path dump.rdb --permissions rw --share-name redis")
+
+    return f"{storage_redis_dump_file_url}?{sas_token}"
+
+
+def main():
+    args = sys.argv[1:]
+    if len(args) != 2 and len(args) != 6:
+        print_usage('Invalid number of arguments')
+        return
+
+    try:
+        ux4iot = parse_ux4iot_args(args)
+        source_storage_account_url = get_dump_file_url(
+            ux4iot['source_subscription_id'], ux4iot['source_resource_group'], ux4iot['source_ux4iot_name'])
+        target_storage_account_url = get_dump_file_url(
+            ux4iot['target_subscription_id'], ux4iot['target_resource_group'], ux4iot['target_ux4iot_name'])
+        print(source_storage_account_url)
+        print(target_storage_account_url)
+        copy_command = f"azcopy copy {source_storage_account_url} {target_storage_account_url}"
+        subprocess.run(copy_command.split(), check=True, text=True)
+    except AttributeError as e:
+        print_usage()
+        print(e)
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

.gitbook/assets/image (1).png

@@ -6,7 +6,7 @@ ux4iot is a tool for directly communicating with your IoT devices from your web
 
 ### General architecture
 
-![](<.gitbook/assets/ux4iot-architecture (1).png>)
+![IoTHub + Ux4iot + Frontend Architecture setup](<.gitbook/assets/ux4iot-architecture (1).png>)
 
 With ux4iot your frontend gets access to Azure IoT Hub's communication primitives without having a custom-built backend middleware translating between IoT Hub and your user interface. No need to design a REST API so that your UI can offer IoT functionality.
 

.gitbook/assets/image (10).png

@@ -4,17 +4,18 @@
 * [Quickstart](quickstart.md)
 * [Concepts](concepts.md)
 * [How Ux4iot works](how-ux4iot-works.md)
+* [REST API Reference](rest-api-reference.md)
+* [Configuration Options](configuration-options.md)
+* [Create your ux4iot Instance](create-ux4iot-instance.md)
 
-## Setup
+## EventHub / IoTHub
 
-* [Create your ux4iot Instance](setup/create-ux4iot-instance.md)
-* [Configure your existing IoT Hub](setup/configure-your-iot-hub.md)
-* [Create IoT Hub and linked ux4iot](setup/create-iot-hub-and-linked-ux4iot.md)
-* [Using a separate Event Hub](setup/using-a-separate-event-hub.md)
+* [Configure your existing IoT Hub](eventhub-iothub/configure-your-iot-hub.md)
+* [Create IoT Hub and linked ux4iot](eventhub-iothub/create-iot-hub-and-linked-ux4iot.md)
+* [Using a separate Event Hub](eventhub-iothub/using-a-separate-event-hub.md)
 
-## Developing web apps with React <a href="#using-react" id="using-react"></a>
+## ux4iot-react <a href="#using-react" id="using-react"></a>
 
-* [Installing the library](using-react/introduction.md)
 * [Initialization](using-react/initialization.md)
 * [Hooks](using-react/hooks.md)
 * [Grant Request Function](using-react/implementing-the-grantrequestforwarder-function.md)
@@ -24,17 +25,15 @@
 
 * [Introduction](implementing-your-custom-security-backend/introduction.md)
 * [Security Backend](implementing-your-custom-security-backend/implementing-the-security-backend.md)
-* [Security Backend Examples](implementing-your-custom-security-backend/security-backend-examples/README.md)
-  * [Azure Function using Javascript](implementing-your-custom-security-backend/security-backend-examples/azure-function-example-for-security-backend.md)
-* [Ux4iot Typescript Client](implementing-your-custom-security-backend/ux4iot-typescript-client.md)
-* [Admin REST API](implementing-your-custom-security-backend/admin-rest-api.md)
+* [Security Backend Example - Azure Function](implementing-your-custom-security-backend/security-backend-examples.md)
+* [ux4iot-admin-node](implementing-your-custom-security-backend/ux4iot-admin-node.md)
 
 ## Resources
 
 * [Pricing](resources/cost.md)
 * [Performance](resources/performance.md)
 * [Limitations](resources/limitations.md)
-* [FAQ](resources/faq.md)
+* [Known Bugs & Nice to know's](resources/faq.md)
 * [Changelog](resources/changelog.md)
 
 ***

.gitbook/assets/image (11).png

@@ -0,0 +1,18 @@
+---
+description: All available deployment options for ux4iot
+---
+
+# Configuration Options
+
+You can generally deploy a ux4iot without specifying any parameters, except for the `iotHubEventHubConnectionString`. This is because we provide default values for all other configuration variables. However we **highly recommend setting a serverVersion. Without it you will deploy the latest code version which is basically a version of a single commit. You will use a development version of ux4iot then.**
+
+The configuration options are somewhat ordered by priority. You will need the last ones the least amount of time. We recommend to deploy a ux4iot service with at least the following configuration variables:
+
+* serverVersion
+* iotHubEventHubConnectionString
+* iotHubServiceConnectionString
+* eventHubConsumerGroup
+* sku
+
+<table data-full-width="true"><thead><tr><th width="311.5">Bicep / ARM Parameter</th><th width="148">Default Value</th><th width="369">Description</th><th>Allowed Values</th><th>type</th></tr></thead><tbody><tr><td>serverVersion</td><td>latest</td><td>ux4iot docker image version to deploy</td><td></td><td>infra</td></tr><tr><td>iotHubEventHubConnectionString</td><td></td><td>The connection string of the EventHub that publishes data you want to subscribe to</td><td></td><td>server</td></tr><tr><td>iotHubServiceConnectionString</td><td>""</td><td>The service connection string of the IoTHub you want to access for devices. <strong>You need to pick a connection string that includes the policies "Registry Read" and "Service Connect"</strong></td><td></td><td>server</td></tr><tr><td>eventHubConsumerGroup</td><td>$Default</td><td>The consumer group of the EventHub that publishes data you want to subscribe to</td><td></td><td>server</td></tr><tr><td>sku</td><td>standard</td><td>The scaling tier of ux4iot. Influences cpu and memory of ux4iot and redis containers within the container app.<br><br>Standard:<br>cpu cores redis: 0.5<br>memory redis: 1Gi<br>cpu cores ux4iot: 1.0<br>memory ux4iot: 2Gi<br><br>Small:<br>cpu cores redis: 0.25<br>memory redis: 0.5Gi<br>cpu cores ux4iot: 0.5<br>memory ux4iot: 1Gi</td><td>standard | small</td><td>infra</td></tr><tr><td>throttlingInterval</td><td>-1</td><td>Throttle time to delay messages put on the websocket for consumers in milliseconds.</td><td></td><td>server</td></tr><tr><td>connectionStateCacheTTL</td><td>60</td><td>Time how long a connection state update is persisted in the internal ux4iot cache, in seconds. Set to -1 set the lifetime to infinity.</td><td></td><td>server</td></tr><tr><td>customTimestampKey</td><td>_ts</td><td>Custom object key of a message to look for the timestamp</td><td></td><td>server</td></tr><tr><td>customDeviceIdKey</td><td>deviceId</td><td>Custom object key of a message to look for the deviceId</td><td></td><td>server</td></tr><tr><td>customConnectionStateKey</td><td>""</td><td>Custom object key of a message to look for the connectionState.</td><td></td><td>server</td></tr><tr><td>connectionStateOnTelemetry</td><td>true</td><td>Flag on whether the connection state of a device should be updated whenever a telemetry message for that device is received.</td><td>true | false</td><td>server</td></tr><tr><td>logLevel</td><td>info</td><td>Sets the initial log level of ux4iot</td><td>error | warn | info | verbose | debug</td><td>server</td></tr><tr><td>location</td><td>resourceGroup().location</td><td>The location where all resources of ux4iot should be deployed</td><td></td><td>infra</td></tr><tr><td>logAnalyticsTracesTableTier</td><td>Analytics</td><td>Tier of the log analytics traces table. <strong>You can only change this value once a week, as dictated by microsoft.</strong><br>Basic Tier will give you less options when querying for logs, but is cheaper. Also the retention time will be set to 7 days instead of 90.</td><td>Basic | Analytics</td><td>infra</td></tr><tr><td>redisVersion</td><td>1.2.0</td><td>redis docker image version to deploy</td><td></td><td>infra</td></tr><tr><td>skipCustomResource</td><td>false</td><td>Skips deployment of the internal function app for the custom resource provider</td><td>true | false</td><td>infra</td></tr><tr><td>skipKeyVaultContents</td><td>false</td><td>Skips deployment of key vault secrets, which leads to the update of the iotHubServiceConnectionStringSecret, iotHubEventHubConnectionStringSecret, storageAccountConnectionStringSecret, backendFuncTriggerUrlSecret</td><td>true | false</td><td>infra</td></tr><tr><td>primaryAdminSecret</td><td>""</td><td>Primary Shared Access Key of the Ux4iot</td><td></td><td>infra</td></tr><tr><td>secondaryAdminSecret</td><td>""</td><td>Secondary Shared Access Key of the Ux4iot</td><td></td><td>infra</td></tr></tbody></table>
+

.gitbook/assets/image (12).png

@@ -0,0 +1,159 @@
+# Create your ux4iot Instance
+
+ux4iot is installed in your Azure subscription as a Managed Application. Billing will be handled by Microsoft.
+
+## Prerequisits:
+
+* You need to have an azure subscription
+* You need to be owner of the resource group that you deploy your ux4iot into. This is because during the deployment, there is a role assigned between managed resources.
+
+### Creating via Azure Marketplace
+
+Visit the [offer on Azure Marketplace](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/deviceinsightgmbh-4961725.ux4iot) and click "Get It Now".
+
+### Creating via Azure Portal
+
+Go to [https://portal.azure.com](https://portal.azure.com) and search for "ux4iot".
+
+### Creating via the command line
+
+If you prefer the command line, the following snippet shows how to do it. See further below for how to retrieve the values for the two parameters.
+
+{% tabs %}
+{% tab title="AZ CLI" %}
+```bash
+RESOURCE_GROUP=ux4iot
+SUBSCRIPTION=yourazuresubscription
+
+az managedapp create \
+  --name ux4iot \
+  --location westeurope \
+  --kind marketplace \
+  --resource-group $RESOURCE_GROUP \
+  --managed-rg-id /subscriptions/${SUBSCRIPTION}/resourceGroups/ux4iot-resources \
+  --plan-product ux4iot \
+  --plan-name standard \
+  --plan-version 1.5.0 \
+  --plan-publisher deviceinsightgmbh-4961725 \
+  --parameters "{\"iotHubEventHubConnectionString\": {\"value\": \"${IOT_HUB_EVENT_HUB_CONNECTION_STRING}\"}, \"iotHubServiceConnectionString\": {\"value\": \"${IOT_HUB_CONNECTION_STRING}\"}}"
+```
+{% endtab %}
+{% endtabs %}
+
+Concerning the parameters: Specifying the Event Hub compatible connection is required. Configuring the service connection string is optional. It is necessary for the following hooks:
+
+* [useDirectMethod](using-react/hooks.md#usedirectmethod)
+* [usePatchDesiredProperties](using-react/hooks.md#usepatchdesiredproperties)
+
+In effect, everything that not only consumes information but accesses the devices in some way.
+
+You can retrieve the service connection string for the IoT Hub with:
+
+```bash
+IOT_HUB_CONNECTION_STRING=$(az iot hub connection-string show \
+  --resource-group RESOURCE_GROUP_OF_IOT_HUB \
+  --subscription SUBSCRIPTION \
+  --hub-name NAME_OF_IOT_HUB \
+  --policy-name service
+  --query connectionString \
+  -o tsv)
+```
+
+You can retrieve the Event Hub compatible endpoint connection string with:
+
+```bash
+IOT_HUB_EVENT_HUB_CONNECTION_STRING=$(az iot hub connection-string show \
+  --resource-group RESOURCE_GROUP_OF_IOT_HUB \
+  --subscription SUBSCRIPTION \
+  --hub-name NAME_OF_IOT_HUB \
+  --query connectionString \
+  --default-eventhub \
+  --policy-name service \
+  -o tsv)
+```
+
+Replace `RESOURCE_GROUP_OF_IOT_HUB` with the resource group that your IoT Hub resides in. Replace`NAME_OF_IOT_HUB` with the name of the IoT Hub. Replace `SUBSCRIPTION` with your Azure Subscription.
+
+### Creating via Bicep (Azure Resource Manager)
+
+Here is an example Bicep template that you can use to deploy a ux4iot instance.
+
+<pre><code>resource managedApp 'Microsoft.Solutions/applications@2019-07-01' = {
+  name: 'ux4iot'
+  kind: 'marketplace'
+  location: resourceGroup().location
+  plan: {
+    name: 'standard'
+    product: 'ux4iot'
+    publisher: 'deviceinsightgmbh-4961725'
+    version: '1.5.0'
+  }
+  properties: {
+    managedResourceGroupId: 'ux4iot-resources'
+    parameters: {
+      // Required
+      iotHubEventHubConnectionString: {
+        value: iotHubEventHubConnectionString
+      }
+      // Optional
+      iotHubServiceConnectionString: {
+        value: iotHubServiceConnectionString
+      }
+      // Optional
+      sku: {
+        value: 'standard'
+      }
+      // Optional
+      eventHubConsumerGroup: {
+        value: '$Default'
+      }
+      // Optional
+      customTimestampKey: {
+        value: '_ts'
+      }
+      // Optional
+      customDeviceIdKey: {
+        value: 'deviceId'
+      }      
+      // Optional
+      primaryAdminSecret: {
+        value: 'supersecret'
+      }
+      // Optional
+      secondaryAdminSecret: {
+<strong>        value: 'supersecretaswell'
+</strong>      }
+      // Optional
+      connectionStateCacheTTL: {
+        value: 60
+      }
+    }
+  }
+}
+</code></pre>
+
+{% hint style="warning" %}
+Notice when you redeploy ux4iot with a different iotHubEventHubConnectionString, **you will need to restart your ux4iot**. You can do this by navigating in the azure portal to your ux4iot instance and clicking the restart button on the top icon bar.&#x20;
+{% endhint %}
+
+{% hint style="info" %}
+Any tags you specify for the managed app will be inherited by the created managed resource group.
+{% endhint %}
+
+Before deploying **for the first time**, you will have to accept the legal terms:
+
+```
+az vm image accept-terms \
+  --publisher 'deviceinsightgmbh-4961725' \
+  --offer 'ux4iot' \
+  --plan 'standard'
+```
+
+You can now deploy the Bicep template:
+
+```
+az deployment group create \
+  --resource-group ux4iot \
+  --subscription yourazuresubscription \
+  --template-file template.bicep 
+```