Skip to main content

Installation of HumanOS IoT Platform

Following products are built on top of HumanOS IoT Platform:

  • ctDataCenter: ICT automation platform
  • ctProduction: Industrial production platform
  • ctSchool: ICT automation platform specialized for swiss schools.

The following document describes in general how to setup the HumanOS IoT Platform.

Preparing Server Environment​

Setup following Server before installing HumanOS IoT Platform:

  • Orchestrator Server (Windows)

    It is also possible to split the micro-services and to run them on different servers.

  • Mosquitto Broker (Linux Server)

    The Mosquitto Broker can also be installed on the Orchestrator Server

  • MariaDB Server (Linux)

    • setup a DB user that is able to fully manage the DBs

  • IPAM server

The Orchestrator Server must have an access to the Mosquitto Broker server using port 1883, and to the MariaDB server using port 3306.

Firewall Rules​

Following firewall rules are needed to run the micro-services of HumanOS IoT Platform:

Name: Access to MariaDB:  
  Source:   Orchestrator Server
  Dest:     MariaDB Server
  Port:     3306

Name: Access to License Platform:  
  Source:   Orchestrator Server
  Dest:     portal.humanos.ch
  Port:     443 (HTTPS)

Name: MQTT Broker
  Source:   Clients (other HumanOS Servers)
  Dest:     Orchestrator Server
  Port:     1883 (TCP)

Name: phpIPAM
  Source:   Orchestrator Server
  Dest:     IPAM Server
  Port:     443 (HTTPS)

Name: Ansible
  Source:   Ansible Control Node
  Dest:     Orchestrator Server
  Port:     8085 (HTTP)

Name: WebApps
  Source:   Clients (other HumanOS Servers)
  Dest:     Orchestrator Server
  Port:     443 (HTTPS)
  Port:     8000 to 9010 (TCP)

Preparing phpIPAM Server​

Navigating to the phpIPAM web address for the first time will present a setup dialog. Follow these steps to complete the setup:

  1. Select "Set up automatic"
  2. If the role phpIPAM was used, you can select "Existing database"
  3. Enter the credentials which were used by the role or setup a new user

Further settings required:

  1. Login

  2. Navigate to Administration -> Server Management -> phpIPAM settings and enable the API to "ON"

  3. Save

  4. Generate an API key Administration -> Server Management -> API

    IMPORTANT: The app id must match the one specified in the device configuration file of the microservice, enter ctdc if you dont know what youre doing.

  5. Install a trusted certificate on the phpIPAM, or download and install the selfsigned certificate on the orchestrator server.

    NOTE: The HumanOS IoT Platform expects a trusted certificate for communication.

    NOTE: Installation of the PEM certificate with power shell:

    certutil.exe -addstore -f "Root" 'C:\Users\path\to\cert.pem'

The API is now setup and ready to use, head here to complete the setup.

Preparing MariaDB Server​

  1. Install latest MariaDB on the linux server

  2. Create the HumanOS Administrator

    1. Open SSH shell 
      > mysql -u root -p
    2. Create user and setup the autorisation 
      MariaDB [(none)]> CREATE USER 'humanos.admin'@'%' IDENTIFIED BY 'humanos';
      MariaDB [(none)]> GRANT ALL PRIVILEGES ON *.* TO 'humanos.admin'@'%' IDENTIFIED BY 'humanos' WITH GRANT OPTION;
      MariaDB [(none)]> FLUSH PRIVILEGES;

  3. Create the HumanOS User

    1. Open SSH shell 
      > mysql -u root -p
    2. Create user and setup the autorisation 
      MariaDB [(none)]> CREATE USER 'humanos'@'%' IDENTIFIED BY 'humanos';
      MariaDB [(none)]> GRANT ALL PRIVILEGES ON *.* TO 'humanos'@'%' IDENTIFIED BY 'humanos' WITH GRANT OPTION;
      MariaDB [(none)]> FLUSH PRIVILEGES;

Preparing Orchestrator Server​

IMPORTANT: All servers and services are up and running (MariaDB, MQTT Broker, ...), before installing the HumanOS IoT platform.

  1. Install the .net 6 Hosting Boundle from official Microsoft site (https://dotnet.microsoft.com/en-us/download/dotnet/6.0)

  2. Install mosquitto broker (https://mosquitto.org/download/)

    Only if the Mosquitto Broker is running on the same server as HumanOS IoT Platform

    • After the installation open file C:\\Program Files\\mosquitto\\mosquitto.conf and change following settings:

      listener 1883
      allow_anonymous true

    • Starting of windows service of Mosquitto Broker.

  3. Install MikTex for PDF generation (https://miktex.org/download)

    1. Choose option to install MikTex for all users

    2. If the server has internet access, choose "Yes" on "Install missing packages on-the-fly", otherwise choose "No"

  4. Run the HumanOS IoT Platform installer (eg. ctDataCenter to install the ctDataCenter modules) The installer will guide you through the process

    1. Basic Settings of the HumanOS IoT Platform

      1. Installation of the HumanOS License file (received from CyberTech Engineering GmbH)

      2. Installation of the private certificate used by the platform endpoints. If the certificate file is left blank, the HumanOS self-signed certificate is used. Following certificates are allowed: .pfx and .p12 If you use the HumanOS self-signed certificate, you have to manually register the certificate in trusted certificate store

        1. Install certificate in folder C:\ProgramData\CyberTech\HumanOS.IoT.Platform\Certificates\HumanOS.self.pfx
        2. Choose "Machine" as "Store Location".
        3. No password is used
        4. Open computer certificate management.
        5. Copy "local" certificate from "Personal" to "Trusted Root Certification Authorities"

      3. Choose a folder for documents, e.g. C:\\HumanOS\\DocumentShare\\

    2. Select the additional micro-services, like AVI load balancer, phpIPAM, ...

    3. Configure the endpoints. By default, localhost is used.

    4. Core micro-services are then automatically started.

NOTE: Some micro-services connect to surrounding systems. They must be provided with additional information, licenses and other settings before they can be started.

Preparing Micro-Service HOS.IPAM.phpIPAM​

The Micro-Service "HOS.IPAM.phpIPAM" is used to manage IP addresses and host objects.

NOTE: Alternatively to HOS.IPAM.phpIPAM, the InfoBlox Micro-Service "HOS.IPAM.InfoBlox" can be used.

Following steps are required to setup HOS.IPAM.phpIPAM:

  1. Make sure phpIPAM server is up and running and certificate of the phpIPAM server is trusted by the orchestrator server

  2. Copy the device information file

    1. navigate to "C:\Program Files\CyberTech\HumanOS.IoT.Platform\HOS.IPAM.phpIPAM\DeviceTemplate\"
    2. Copy file "ipam.json" to "C:\ProgramData\CyberTech\HumanOS.IoT.Platform\devices\HOS.IPAM.phpIPAM\" folder.

  3. Get a device license from HumanOS Portal

    1. Choose "HumanOS.UHAL.WebControl" als Connector

    2. Set address, like "https://doc01-003-ctopa.dev.ctdatacenter.com"

  4. Open the device information model file

    1. Add license key to the "Id" property of the device
    2. Add the correct address to the "Address" property
    3. Put the API Key from above to the property called "CustomHeader:phpipam-token".

    Example:

    {
      "Id": "164cb843-6251-ab23-b353-8621200f9acd",
      "Name": "phpIPAM Dev System",
      "DriverId": "BE79A86B-38EE-4FAA-805A-1DB46A06E65D",
      "Address": "https://doc01-003-ctopa.dev.ctdatacenter.com",
      "Properties": [
        {
          "Name": "DeviceType",
          "Value": "phpIPAM"
        },
        {
          "Name": "Accept",
          "Value": "application/json"
        },
        {
          "Name": "ContentType",
          "Value": "application/json"
        },
        {
          "Name": "CustomHeader:phpipam-token",
          "Value": "Lqt82MMoF1723D183sjad-asdfdddaWzd"
        },
        {
          "Name": "AppId",
          "Value": "ctdc"
        }
      ],
      ...
    }

  5. Go to Windows Services and start micro-service "HOS.IPAM.phpIPAM".

Preparing Micro-Service HOS.ITInfrastructure.Reporting​

The Micro-Service "HOS.ITInfrastructure.Reporting" is used to report ICT objects to outside systems. By default, the reporting service sends data to the HermanOS, which collects the SLA data and generates invoices for platform customers.

Following steps are required to setup HOS.ITInfrastructure.Reporting:

  1. Make sure HOS.HermanOS micro-service is installed and properly configured.

  2. Copy the device information file

    1. navigate to "C:\Program Files\CyberTech\HumanOS.IoT.Platform\HOS.ITInfrastructure.Reporting\DeviceTemplate\"
    2. Copy file "reporter.json" to "C:\ProgramData\CyberTech\HumanOS.IoT.Platform\devices\HOS.ITInfrastructure.Reporting\" folder.

  3. Get a device license from HumanOS Portal

    1. Choose "HumanOS.UHAL.WebControl" als Connector

    2. Set address, like "https://localhost:8084"

  4. Go to Windows Services and start micro-service "HOS.ITInfrastructure.Reporting".

Example:

{
  "Id": "7540e33b-2775-4f7a-a44f-418f0edcc67e",
  "Name": "ICT Reporting",
  "DriverId": "BE79A86B-38EE-4FAA-805A-1DB46A06E65D",
  "Address": "https://localhost:8084",
  "Properties": [
    {
      "Name": "DeviceType",
      "Value": "ValueReporter"
    },
    {
      "Name": "Accept",
      "Value": "application/json"
    },
    {
      "Name": "ContentType",
      "Value": "application/json"
    },
    {
      "Name": "ApiVersion",
      "Value": "v2"
    }
  ]
  ...
}

Setup the Platform​

  1. Open the URL https:///{your WebServer Name}

    The setup page should appear.

    • Admin password
    • Admin Tenant name

  2. Enable the Modules of your platform

  3. Input additional settings

    • Your username and password of the HumanOS Portal (used to get automatically licenses)

Ready to rule the world!

Appendix

Installation Path​

Binaries​

The Platform binaries is installed by default in "C:\ProgramFiles\CyberTech\HumanOS.IoT.Platform\".

Each Micro-Service is located in its own directory, e.g. "$(InstallDir)HOS.Administration\".

Customer Files​

The customer files of the platform are generated in "C:\ProgramData\CyberTech\HumanOS.IoT.Platform\".

  • appsettings.json: Customer settings of the HumanOS IoT Platform and its micro-services
  • .\Licenses\: Folder containing the license files of the platform
  • .\Certificates\: Folder containing the private certificates used for the platform endpoints.
  • .\Devices\: Folder containing the device information models to bind other systems to the platform
  • .\{{MicroService}}\: Folder containing the logfile, dumps etc. from the micro-service {{MicroService}}

Changing Configuration after Installation​

IMPORTANT: Before changing the configuiration of the platform, make sure all micro-services are stopped.

IMPORTANT: When adding your own private certificate, make sure the certificate file contains only the private certificate (no CA or intermediate certificates).

Open the "appsettings.json" in "C:\ProgramFiles\CyberTech\HumanOS.IoT.Platform\"

Common Settings​

The JSON object "MicroServices:Common" contains the commom configuration applied to all micro-services.

  • DevicePath: Path of the device information model
  • CertificateFile: Private certificate file name
  • CertificatePassword: Password of the private certificate. Leave empty if no password is needed.
  • LicenseManagerEndpoint
    • Address: Access to the internal license management. The endpoint is configured in HOS.Administration micro-service
  • DataBaseEndpoint: persistance storage
    • Address: server name of the MariaDB server
    • UserName: HumanOS user. Must have all management rights of the data base
    • Password: password of the user
  • SharedNodespaceEndpoint: communication layer between micro-services
    • Address: server name of the mosquitto broker (MQTT)

HOS.Administration Service​

The HOS.Administration micro-service provides the license management endpoint, deploying HumanOS platform and device licenses to all other micro-services The micro-service is customized by JSON object "MicroServices:HOS.Administration":

  • LicenseManagerEndpoint:
    • CertificateFile: Private certificate file for this endpoint. By default, this points to the common settings.
    • CertificatePassword: Password of the private certificate. By default, this points to the common settings.

HOS.IdentityServer​

The HOS.IdentityServer micro-service provides endpoints to authenticate users and clients. The micro-service is customized by JSON object "MicroServices:HOS.IdentityServer":

  • Endpoint:
    • Address: endpoint address, e.g. https://localhost:8443
    • CertificateFile: Private certificate file for this endpoint. By default, this points to the common settings.
    • CertificatePassword: Password of the private certificate. By default, this points to the common settings.

HOS.WebPortal​

The HOS.WebPortal micro-service provides http/https web front-end. The micro-service is customized by JSON object "MicroServices:HOS.WebPortal":

  • Endpoint:
    • Address: endpoint address, e.g. https://localhost:8080
    • CertificateFile: Private certificate file for this endpoint. By default, this points to the common settings.
    • CertificatePassword: Password of the private certificate. By default, this points to the common settings.
    • AlternativeRedirectUrl_1: first alternative redirected URL
    • AlternativeRedirectUrl_2: second alternative redirected URL

Use IP-address or CNAME of the server as alternative redirected URLs.