SCRAL - Deploy a SCRAL Module

This tutorial will help you to understand how to deploy and run a SCRAL module from the dockerhub or directly from the source code.

Alternatively, if you want to understand how to develop your own SCRAL module, please have a look at the SCRAL development tutorial.

• Prerequisites
  • Docker
  • GOST
• SCRAL quickstart with docker-compose
  • Quickstart introduction
  • Before Starting
  • Testing SCRAL capabilities
• Run SCRAL Python code
  • Python Packages
  • Running a SCRAL module from the source code

Prerequisites

Docker

To start working with SCRAL it is necessary to have Docker installed on your machine. To install the proper version for your operating system, have a look to the Docker documentation page.

GOST

SCRAL depends on the GOST server, a Go implementation of the Sensing OGC SensorThings API. To learn more about OGC and GOST visit the GOST GitHub page or the MONICA tutorial about OGC Historical Data Retrieval & Visualizations.

SCRAL quickstart with docker-compose

SCRAL is an IoT adaptation framework that contains different adapters, called also resource managers. In the SCRAL source code repository, you can find a docker-compose template to start working with SCRAL and GOST. You just need to modify only the name of the adapter (corresponding to the name of the SCRAL image).

This docker-compose file integrate the GOST environment and all the possible SCRAL enviromental variables. Note that the variables that are not commented are mandatory.

Quickstart introduction

A user can initiate a “quickstart” docker-compose file going inside “docker-compose” folder published inside SCRAL repository and running the command:

$ docker-compose -f <file_name> up -d

Before Starting

For running a SCRAL docker-compose, it is necessary to set few environmental variables:

• To enable the usage of the other environmental variables it is necessary to have the variable “CONFIG” set to value “custom”.

• To start a SCRAL module it is necessary to specify the name of the docker image to load (e.g.: monicaproject/scral:glasses)

scral:
    image: monicaproject/scral:${SCRAL_MODULE}
    container_name: "SCRAL-${SCRAL_MODULE}"
    environment:
        CONFIG: custom

Note 1: you can run only a quickstart image present inside the SCRAL archive of MONICA docker-hub.

Note 2: for certain modules it is necessary to specify additional environmental variables, for more details have a look to the MONICA SCRAL dockerhub.

Testing SCRAL capabilities

When the SCRAL is up and running, the adapter is able to manage data flow mainly through either REST or MQTT messages. You can interact with SCRAL using the APIs available here.

Each SCRAL module exposes also a landing web-page useful for both testing the reachability of the endpoint and having a quick overview of the available SCRAL APIs (e.g.: for gps_tracker_rest the URL is http://localhost:8000/scral/v1.0/gps-tracker-gw).

Run SCRAL Python code

The SCRAL source code is available in MONICA project repository. It is possible to fork (or simply download) the repository and start working directly on the source code. As already mentioned, it is necessary to have already started a GOST docker instance to make SCRAL properly working. To do that, it is possible to download a docker-compose file from GOST repository or to start the file “docker-compose-gost.yml” contained inside the “docker-compose” folder of SCRAL repository through the command:

$ docker-compose -f docker-compose-gost.yml up -d

Python Packages

To work properly with the SCRAL, it is required the following Python packages (with the recommended versions):

• Eclipse Paho 1.5
• Flask 1.0.2
• CherryPy 18.1.0
• arrow 0.14.2 (arrow 0.15 not supported)
• requests 2.22.0
• configparser 3.7.1

Running a SCRAL module from the source code

To give to developers the possibility to quickly switch between different configurations, SCRAL can work also using configuration files. The configuration files must be called “preference.json”. If nothing is specified, in each module folder, the default configuration file must be stored inside “config/local”.

When you start working with SCRAL, you can decide if you prefer to modify the content of the default file, or if you want to create a new folder inside the already existing “config” folder (e.g.: “config/my_config_folder”).

To start an execution just go in the SCRAL main folder and run the following command:

python <module_name>/<start_module.py> -p <my_config_folder>

For example, if you want to start the SCRAL tha integrates the smart glasses module and you want to store your preferences inside: “smart_glasses/config/test/preferences.json”, you can run the following command:

python smart_glasses/start_smart_glasses.py -p test

Note: if the environmental variable CONFIG exists and it is set to “custom” then the configuration file is not read.

Once that the SCRAL module is up and running, you can have access to its APIs surfing the “entry endpoint” of the module (e.g.: for gps_tracker_rest the URL is http://localhost:8000/scral/v1.0/gps-tracker-gw). A complete list of API is avaiable on SwaggerHub.