Deploy and Connect Devices¶

To deploy the IoTC locally. For example on an PC or Raspberry Pi:

1. Go to the /deploy/local_deployment/ directory

2. Open the docker-compose.yml file and add the following environment variables:

   1. **IOT_LICENSE_KEY **

      In ingress and engine. See License key notes for details.

      ingress:
          image: enocean/iotconnector_ingress:latest
      environment:
              - IOT_LICENSE_KEY= #enter license here, be sure not to have empty space after "=" e.g. IOT_LICENSE_KEY=LBIBA-BRZHX-SVEOU-ARPWB
      
      engine:
          image: enocean/iotconnector_engine:latest
          environment:
              - REDIS_URL=redis
              - IOT_LICENSE_KEY= #enter license here, be sure not to have empty space after "=" e.g. IOT_LICENSE_KEY=LBIBA-BRZHX-SVEOU-ARPWB
      

   2. IOT_AUTH_CALLBACK

      The IOT_AUTH_CALLBACK is formed by taking the IP address or hostname of your instance + :8080 . If you are working on a local network with DHCP make sure the IP address stays static.

      ingress:
          image: enocean/iotconnector_ingress:latest
      
          environment:
              - IOT_AUTH_CALLBACK= #enter URL here e.g. 192.167.1.1:8080 or myiotc.eastus.azurecontainer.io:8080
      

   3. IOT_GATEWAY_USERNAME & IOT_GATEWAY_PASSWORD

      Create a IOT_GATEWAY_USERNAME and IOT_GATEWAY_PASSWORD. These two environment variables are needed for the connection between Aruba AP and IoTC.

      ingress:
          image: enocean/iotconnector_ingress:latest
      
          environment:
              - IOT_GATEWAY_USERNAME= #enter new username for the AP connection to IoTC. e.g. user1
              - IOT_GATEWAY_PASSWORD= #enter new password for the AP connection to IoTC. e.g. gkj35zkjasb5
      

   4. BASIC_AUTH_USERNAME & BASIC_AUTH_PASSWORD

      The selected username and password will be used to access the API and its web UI.

      proxy:
          image: enocean/proxy:latest
      
          environment:
              - BASIC_AUTH_USERNAME=  #enter new username for API connection of IoTC. e.g. user1
              - BASIC_AUTH_PASSWORD=  #enter new password for API connection to IoTC. e.g. 5a4sdFa$dsa
      

   5. PROXY_CERTIFICATE & PROXY_CERTIFICATE_KEY

      Configure the secrets for the NGINX proxy with the .crt, .key files you have prepared.

      #secrets are defined by docker to keep sensitive information hidden
      secrets:
          secret-proxy-certificate:
              file: ../nginx/dev.localhost.crt # specify path to .crt
          secret-proxy-key:
              file: ../nginx/dev.localhost.key # specify path to .key
      

      Note

      For advanced users, if you need to make changes to the NGINX proxy the Dockerfile, start.sh and nginx.conf are available in the /deploy/nginx folder and can be changed and rebuilt as necessary.

   6. Select the end-point for the IoTC.

      Azure IoT Hub or MQTT client is available. At least one end-point must be enabled.

      Azure IoT HubMQTT

      List IOT_AZURE_CONNSTRING & IOT_AZURE_ENABLE.

          engine:
              image: enocean/iotconnector_engine:latest
                  environment:
                  # Comment this section out, should Azure egress not be desired.
                      - IOT_AZURE_ENABLE=1
                      - IOT_AZURE_CONNSTRING=HostName=testhub.azure-devices.net;DeviceId=device;SharedAccessKey=FxyfIfddsgd4+r2/kk6d36Wkmlgsfd+Vyo8uPV8JmY5+pmM=
      

      The Azure Connection string refers to an IoT device inside your Azure IoT Hub. Go to your Azure IoT Hub to get it.

      List MQTT_CONNSTRING & IOT_ENABLE_MQTT.

          engine:
              image: enocean/iotconnector_engine:latest
              environment:
                  - IOT_ENABLE_MQTT=1 # comment this section out if mqtt is not desired
                  - MQTT_CONNSTRING=127.0.0.1:1883  # comment this section out if mqtt is not desired. Default path is locally deployed mosquitto broker - for tests only.
      

      Note

      For native docker (local) deployments use mqtt:1883 for MQTT_CONNSTRING. For Azure docker instances (ACI) deployments use 127.0.0.1:1883 for MQTT_CONNSTRING.

      Optionaly change the MQTT client ID. If no MQTT Client ID is provided then a random one is generated and used.

          engine:
              image: enocean/iotconnector_engine:latest
              environment:
                  - IOT_MQTT_CLIENT_ID=iotc_test_instance_1
      

      For your convenience a mosquitto broker is listed as a container instance in the docker-compose.yml. The broker interfaces are not protected, it is only used as a demonstration. If you have your own MQTT broker or you do not use MQTT as endpoint delete this listing in thedocker-compose.yml:

          mqtt:
              image: eclipse-mosquitto:1.6.13
                  ports:
                      - "1883:1883"
      

3. Save the changes and run from the /deploy/local_deployment/ directory

   #run
   docker-compose up -d
   
   #see the Docker UI for successful deployment or run
   docker ps
   #If you need change something and redeploy do not forget to the command before redeploying
   docker-compose down
   

4. The IoTC will now be reachable at IP address or hostname of your instance. You can check by calling the web UI of the API at e.g. https://<IP address or hostname>:443 in your web browser. e.g. https://192.167.1.1:443

1. Download and install the Azure CLI
2. Go to the azure_deployment directory

3. Open docker-compose.yml file add the following environment variables:

   1. IOT_LICENSE_KEY.

      In ingress and engine. See License key notes for details.

      ingress:
          image: enocean/iotconnector_ingress:latest
      environment:
              - IOT_LICENSE_KEY= #enter license here, be sure not to have empty space after "=" e.g. IOT_LICENSE_KEY=LBIBA-BRZHX-SVEOU-ARPWB
      
      engine:
          image: enocean/iotconnector_engine:latest
          environment:
              - REDIS_URL=localhost
              - IOT_LICENSE_KEY= #enter license here, be sure not to have empty space after "=" e.g. IOT_LICENSE_KEY=LBIBA-BRZHX-SVEOU-ARPWB
      

   2. IOT_AUTH_CALLBACK.

      The IOT_AUTH_CALLBACK is formed by taking the IP address or hostname of your instance + :8080 . The URL consists of <yourDomainName>.<yourRegion>.azurecontainer.io. - <yourDomainName> is specified in step 6. - <yourRegion> is specified when you create the Azure resource group. Check this article for a hint.

      ingress:
          image: enocean/iotconnector_ingress:latest
      
          environment:
              - IOT_AUTH_CALLBACK= #enter URL here e.g. myiotc.eastus.azurecontainer.io:8080
      

   3. IOT_GATEWAY_USERNAME & IOT_GATEWAY_PASSWORD

      Create a IOT_GATEWAY_USERNAME and IOT_GATEWAY_PASSWORD. These two environment variables are needed for the connection between Aruba AP and IoTC.

      ingress:
          image: enocean/iotconnector_ingress:latest
      
          environment:
              - IOT_GATEWAY_USERNAME= #enter new username for the AP connection to IoTC. e.g. user1
              - IOT_GATEWAY_PASSWORD= #enter new password for the AP connection to IoTC. e.g. gkj35zkjasb5
      

   4. BASIC_AUTH_USERNAME & BASIC_AUTH_PASSWORD The selected username and password will be used to access the API and its web UI.

      proxy:
          image: enocean/proxy:azure
      
          environment:
              - BASIC_AUTH_USERNAME=  #enter new username for API connection of IoTC. e.g. user1
              - BASIC_AUTH_PASSWORD=  #enter new password for API connection to IoTC. e.g. 5a4sdFa$dsa
      

   5. PROXY_CERTIFICATE & PROXY_CERTIFICATE_KEY

      See description in local deployment.

   6. Set domainname for the proxy service.

          proxy:
              image: enocean/proxy:azure
              ports:
                  - "443:443"
                  - "80:80"
                  - "8080:8080"
              secrets:
                  - source: secret-proxy-certificate
                  target: /etc/nginx/certs/cert.crt
                  - source: secret-proxy-key
                  target: /etc/nginx/certs/cert.key
              domainname: "yourDomainName" # specify the name of your domain. This is then used in also in IOT_AUTH_CALLBACK
      

   7. Select the end-point for the IoTC.

      See description in local deployment.

   8. Select the volume storage.

      To have persistent storage settings executed on the API, a persistent storage needs to be provided. This is optional, simply delete the section if it is not required, otherwise set your-volume-name and mystorageaccount to match your Azure volumes names.

          volumes:
              redis-volume:
                  driver: azure_file
                  driver_opts:
                      share_name: your-volume-name
                      storage_account_name: mystorageaccount
      

   9. Configure Azure with selected parameters.

      Microsoft Azure cloud account and subscription required. Be sure to use the same parameters names as configured in docker-compose.yml:

      • yourResourceGroupName
      • yourRegion
      • your-volume-name
      • mystorageaccount

4. Save the changes and run from the /deploy/azure_deployment/ directory

       # Create an Azure Resource Group. yourRegion is used in the URL for     IOT_AUTH_CALLBACK.
       # run "az account list-locations -o table" to see available locations
       # yourResourceGroupName can be a new or existing resource name group
       az group create --name yourResourceGroupName --location yourRegion
       # Login to Azure using docker, web browser will open to enter credentials
       docker login azure
       # Create a docker ACI (Azure Container Instances) context
       docker context create aci myacicontext
       # Activate context
       docker context use myacicontext
       # Set up storage. More info here: https://docs.docker.com/cloud/aci-integration/
       # By default, if the storage account does not already exist, this command creates a new storage account using the Standard LRS as a default SKU, and the resource group and location associated with your Docker ACI context.
       docker volume create your-volume-name --storage-account mystorageaccount
       #Deploy the IoTC to Azure
       docker compose up
       #Return to default context
       docker context use default
   

5. The IoTC will now be reachable at yourDomainName.yourRegion.azurecontainer.io. You can check by calling the web UI of the API at https://yourDomainName.yourRegion.azurecontainer.io:443 in your web browser.