Skip to main content Skip to footer

Node Installation

The first step when installing a local edge Node is to register the Node in Crosser Control Center to get the credentials. This is covered in the In Crosser Control Center section below.

There are two options for installing a Crosser Node on a local server: using a Docker Linux container (recommended for Linux systems) or as a Windows service (recommended for Windows systems). Follow the steps in either Installing a local Crosser Node using Docker or Installing a local edge Node as a Windows service below, depending on your choice of platform.

In Crosser Control Center

1: Register a key

You have 2 options when registering a new Node:

  1. Register a single Node (can be used only once)
  2. Register a global key to be used within your organization for a limited time

Single Node

To register a single Node:

  • Navigate to ‘Nodes’ in the menu and select the tab ‘Register Nodes’
  • Enter a name for your Node and click ‘Add’
  • The Node is now added and by clicking ‘Show Credentials’ you can get the Id and Access Key for the Node. Keep them for later use.

Global Key

This can only be done by the organization administrator. To define a global key:

  • Navigate to ‘Organization’ in the User menu select the menu item ‘Registration Keys’
  • Define a date interval the key is valid for and click ‘Generate Key’
  • The key is now generated and by clicking ‘Show Registration Key’ you can get the key. Keep it for later use.

Installing a local Crosser Node using Docker

Prerequisites

You have a platform that supports the minimum requirements:

  • Docker is installed
  • Docker Compose is installed

1: Login to docker.crosser.io

Open a terminal and enter:

[sudo] docker login https://docker.crosser.io

When prompted, enter the username and password which you find in the ‘Docker Credentials’ section on the ‘Register Node’ tab on the Nodes page (you have to enable ‘Advanced Settings’ to see this).

2: Get docker-compose.yml

To be able to use docker-compose you need a configuration file. Download the file docker-compose.yml into a local folder, or copy the content below into your own docker-compose.yml

    version: '3.5'
services:
  edgeNode:
    image: docker.crosser.io/crosser/edgeNode:latest
    container_name: crosser-edgeNode
    restart: always
    environment:
      - SecurityConfiguration__Credentials__NodeId=ENTER-YOUR-NODEID-HERE
      - SecurityConfiguration__Credentials__AccessKey=ENTER-YOUR-ACCESS-KEY-HERE
    ports:
      - 9090:9090
      - 9191:9191
      - 1883:1883
    volumes:
      - "./data:/application/data"
    logging:
      driver: json-file
      options:
        max-size: "50m"
        max-file: "2"

3: Setup Credentials

With Node key

Replace ENTER-YOUR-NODEID-HERE and ENTER-YOUR-ACCESS-KEY-HERE in your docker-compose.yml file with the values you got when registering the Node above.

With global key

In the docker-compose.yml file replace these two lines:

- SecurityConfiguration__Credentials__NodeId=ENTER-YOUR-NODEID-HERE
- SecurityConfiguration__Credentials__AccessKey=ENTER-YOUR-ACCESS-KEY-HERE

with these lines:

- SecurityConfiguration__Registration__Key=ENTER-YOUR-GLOBAL-KEY-HERE
- SecurityConfiguration__Registration__Name=UNIQUE-NAME-HERE

Then replace ENTER-YOUR-GLOBAL-KEY-HERE with the global registration key you, or your administrator, generated and replace UNIQUE-NAME-HERE with the name you want to give the Node (only alphanumeric characters and underscore are allowed in Node names).

4: Proxies

If the Crosser Node is running behind a proxy you need to add configurations in the environment section, just like you did with the credentials above.

Node versions 2.6 and higher

https_proxy=user:pw@192.168.102.10:1180

In analogy with this, http_proxy is set by:

http_proxy=user:pw@192.168.102.10:1180

See the Environment Settings page for more proxy settings.

Node versions <2.6

httpsProxy=192.168.102.10

In analogy with this, httpProxy is set by:

httpProxy=192.168.102.10

5: Start the Node

Run this command from the folder where you created the docker-compose.yml.

[sudo] docker-compose up -d

The Node will be downloaded from the docker registry and started.

6: Ready to go

If no errors were reported your Node is now up and running and connected to Crosser Control Center (check that you have a green checkmark next to the Node on the Nodes or Dashboard pages).

Next, start to build and deploy some flows on your new Node.

Good luck!

Installing a local Crosser Node as a Windows service

Prerequisites

You have a platform that supports the minimum requirements.

1. Download the installer

Login to Crosser Control Center

Download the Windows installer from the Nodes page, on the Register Nodes tab. On this tab enable Advanced settings to open up the list with downloadable files. Download the file for the version you want to install and unzip it in a directory on your local host server. This directory will be used to store configuration data used by the Node, so make sure to select a directory that is persistent, i.e. not a temp directory that might be cleaned by some background process.

Note that you need Nodes: Create permission to access the Register Nodes tab.

2. Install the Windows service

Note: The installer is implemented as a PowerShell script, therefore scripting must be enabled in PowerShell for scripts downloaded from the Internet. You can check your current execution policy with:

Get-ExecutionPolicy

Make sure it’s one of UnRestricted or Bypass, if not use the following command to change it:

Set-ExecutionPolicy -Scope Process UnRestricted

To install the Node, open a PowerShell window as Administrator, in the directory where you stored the installer. Then run:

.\InstallWindowsService.ps1

You will be asked to provide the Id and Access Key credentials you obtained when registering the Node in Crosser Control Center. Note that only single Node credentials can be used with the Windows service installer. Contact support@crosser.io if you want to use global registration keys with a Windows service installation.

At the end of the installation you will be asked to type run to start the service. If you don’t do this the service will just be installed and you will then have to open the Services app to start the service.

3: Proxies

If your server sits behind a proxy and the proxy configuration is not managed by Windows you need to set an environment variable to tell the Node how to reach the proxy. Choose one of the two options below, depending on if your proxy uses HTTP or HTTPS. You need to set this before starting the Crosser service:

Node version 2.6+

In PowerShell:

$env:http_proxy = 'user:pw@192.168.102.10:1180'
$env:https_proxy = 'user:pw@192.168.102.10:1180'

See the Environment Settings page for more proxy settings.

Node versions <2.6

In PowerShell:

$env:httpProxy = 'user:pw@192.168.102.10:1180'
$env:httpsProxy = 'user:pw@192.168.102.10:1180'

4: Python setup (optional)

If you want to use the Python Bridge module, Python 3.x must be installed on your machine. In addition you need to configure the path to the Python interpreter in the appsettings.json file, which can be found in the Host\data folder in the same directory where you installed the Node. In the ExternalPrograms section modify the path to your Python executable.

If you are not sure about the path to your executable, you can use the following command from your Windows Command Line or Powershell:

PS C:\Users\myuser> python -c 'import os, sys; print(os.path.dirname(sys.executable))'
C:\Program Files\Python311

Your appsettings.json file should then look something like this:

{
  "EdgeNodeConfiguration": {
    "SERVER_CONFIGURATION_VERSION": 2.9,
    "LogLevel": "Information",
    "ExternalPrograms": {
      "Python3": "C:/Program Files/Python311/python.exe"
    }
  }
}

Alternatively you can add the path to the Python executable as a an environment variable:

$env:python3Path = 'C:/Program Files/Python311/python.exe'

You also need to install the Paho MQTT library into your Python setup, e.g:

pip install paho-mqtt==1.6.1

or

conda install -c sci-bots paho-mqtt==1.6.1

5: Ready to go

If no errors were reported your Node is now up and running and connected to Crosser Control Center (check that you have a green checkmark next to the Node on the Nodes or Dashboard pages).

Next, start to build and deploy some flows on your new Node.

Good luck!

Installing a Crosser Node on an Azure IoT Edge device

The Crosser Node is available on the Azure IoT Edge marketplace and can be installed like any other module, search for Crosser and you should find CrosserIoTEdgeStreamingAnalytics.

Prerequisites

  • You have a running IoT Edge device

1: Adding credentials

You have to add the Node credentials (see In Crosser Control Center above) to the module configuration. The Id and Access key are added as environment variables and you just need to copy the values you got from Crosser Control Center into these environment variables.

2: Updating Docker image (optional)

The Docker image on the IoT Edge marketplace may not be the latest version. If you want to use the latest version you have to add the Crosser Docker repository to the list of repositories available for your IoT Edge device. You can do this on the Set Modules page, under Container Registry Credentials, in the Azure portal. See Installing a local Crosser Node using Docker above for information on the Crosser repository.

After adding the repository you need to change the Image URI reference in your deployment configuration. Replace the current Image URI for the CrosserIoTEdgeStreamingAnalytics module to:

docker.crosser.io/crosser/edgeNode:latest

This is all you need to do. Once you update the IoT Edge configuration the device will download the latest Crosser container from our repository and start the Node, which then registers with Crosser Control Center. To confirm successful installation the status for your Node will change to Online (green checkmark) on the Nodes and Dashboard pages in Crosser Control Center.

Crosser Node as Azure Container App

Introduction

Beside running the Crosser Node on a stand-alone Docker setup, or using a container orchestration system like Kubernetes/OpenShift, you can also run the Node as an Azure Container App in your Azure infrastructure. This gives you the advantage of not having to deal with overhead like resources and management of an operating system which hosts the Node. In addition, Azure Container Apps allow you to scale the resources of your container in a smooth and easy way making it highly adjustable for your use case.

Prerequisites

The Crosser Node requires persistent local storage which allows the Node to store log files, settings, deployed flows and other things. If you run the Node as an Azure Container App without persistent storage, the Node will run just fine but it will lose all deployed flows with every restart. To avoid that you will need to add a File Share to your Container AppEnvironment.

Setup

The steps below should be treated as guidelines and you might want to adjust certain settings according to your needs or infrastructure.

Create File Share

In your Azure portal navigate to ‘Storage Accounts’, add a new storage or use an existing one and add a ‘File Share’ to it. Keep in mind that every Node will require one unique File Share.

You will later on need the name of the File Share to map it into the Container.

On your storage account, move to ‘Access keys’ and show/copy one of the available keys for your storage account.

You will need the ‘Access key’ later on.

Create Container App

In your Azure portal, go to ‘Container Apps’ and click create. Specify the basic settings according to your needs and click ‘Next: Container’.

The Crosser Node is available on Crosser’s Docker repository. You can get the credentials for that in Crosser Control Center.

Add the password here as well.

Specify the Container resource allocation according to your needs. With the smallest possible setup (0,5 CPU cures, 1 Gi memory) you can run the Crosser Node.

For Environment variables, you have to add at least:
SecurityConfiguration__Credentials__NodeId
SecurityConfiguration__Credentials__AccessKey

NodeID and AccessKey are the Node credentials that you get when creating the Node in your Crosser Control Center organization

If you want to expose ports from the Node, you can specify the Ingress settings according to your needs. By default the Node comes with a webserver and internal MQTT Broker which allow communication to external services.

Port 9090: Default web server for receiving data in Flows using the HTTP Listener module.
Port 9191: Node web UI and monitoring REST API
Port 1883: MQTT Broker

For our basic setup we do not expose any ports.

Follow the next steps and click ‘create’.

Deploy container

Once the Container App is created, click on the name, navigate to ‘Containers’ and click on ‘Edit and deploy’.

Select the container image and click ‘Edit’

Go to ‘Volume mounts’ and click on the link ‘Container Apps environment’ to define the file share it should be mapped into the container.

Once you are redirected to ‘Container Apps Environment’, go to ‘Azure Files’ and click ‘Add’.

For Name you can specify whatever you want, in our example we go with ‘data’. Specify other settings according to the File Share that was created previously. Make sure you use Read/Write permission.

When created, your share should look something like this:

 

Afterwards, mount the volume to your container deployment by adding it as shown below.

If desired you can add ‘Health probes’ that check if the container is running properly. To do so, we recommend the settings below.

Now your Setup is completed and you can deploy your Container App.

Verify

To verify that the container is up and running, you can move to ‘Container Apps’, Application and navigate to ‘Revisions’.

In addition we recommend checking whether or not the Node is shown as online in your Crosser Control Center organization.

Also, once the Node is running, you should find the usual known folder structure in the File share which was added to the Container deployment.