Create a Docker App

A Docker App is a standard docker container and is created and developed like any normal container for docker and Kuberenetes.

You can build for both x86_64 and arm64 devices.

At a minimum to be compatible with Kelvin, you need two files.

For this example we will get ready for deploying a stock Node Red Server to the edge which can then be accessed on the local LAN network at port 1880 in any modern broswer.

app.yamlDockerfile

The app.yaml is the main configuration file that holds both Kelvin SmartApps™ definition as well as the deployment/runtime configuration.

For our example it would look like this;

app.yaml Example
spec_version: 5.0.0
type: docker

name: nodered-server
title: Node Red Server
description: A local Node Red Server running at the edge.
version: 1.0.0

flags:
  enable_runtime_update:
    configuration: false

ui_schemas:
    configuration: "ui_schemas/configuration.json"

defaults:
  system:
    ports:
      - name: http
        type: host
        host:
          port: 1880
    privileged: false
    volumes:
      - name: data
        target: /data
        type: persistent
  configuration:
    ip-range: 0.0.0.0
    port: 1880

It is composed by the following sections:

The spec_version section is automatically injected and specifies Kelvin SmartApps™ JSON Schema(latest) version which both defines and validates the app.yaml structure.
app.yaml Example
1
spec_version: 5.0.0
The type section defines the type for the application.
- app: A Smart App that allows mapping inputs and outputs to data streams, sending control changes, recommendations, and data tags.
- docker: An docker application that does not connect to the platform's data streams.
- importer: Connects to an external system to import data into the platform as well as receive control changes to act on the external system.
- exporter: Connects to the platform to export data to an external system.
app.yaml Example
1
type: docker
The info section holds Docker App's basic information required to make itself uploadable to Kelvin's App Registry.
app.yaml Example
1 2 3 4
description: Local Node Red Server Demo name: local-node-red-server-demo title: Local Node Red Server Demo version: 1.0.0
The name is the Docker App's unique identifier.

The title and description will appear in App Registry on the Kelvin UI once the Docker App is uploaded.

Info

The version should be bumped every time Docker App gets an update, and before it gets uploaded to the App Registry.

The upload will be rejected if there is the version already exists on the Kelvin Platform.

The flags section is where you are able to set some of the application capabilities.

app.yaml Example
flags:
enable_runtime_update:

    # enables configuration updates at runtime
    configuration: false 

The ui_schemas section is where the Docker App configuration is defined for the Kelvin UI.

The actual information is kept in a json file in the ui_schemas folder of the project. The file location is defined in the app.yaml file like this;

app.yaml Example
ui_schemas:
configurations: "ui_schemas/configurations.json"

The json file will come with default blank schemas when first created.

Note

configurations.json information is optional, and if not provided, the Kelvin UI will display the configuration settings in a raw JSON or YAML file format without verifying the structure or content before applying them to the Kelvin SmartApp™.

Default ui_schemas/configurations.json
{
    "type": "object",
    "properties": {},
    "required": []
}

An example of a App Configurations JSON file filled in would look something like this;

Sample ui_schemas/configurations.json
{
    "type": "object",
    "properties": {
        "closed_loop": {
            "type": "boolean",
            "title": "Closed Loop"
        },
        "speed_decrease_set_point": {
            "type": "number",
            "title": "Speed Decrease SetPoint",
            "minimum": 1000,
            "maximum": 3000
        },
        "temperature_max_threshold": {
            "type": "number",
            "title": "Temperature Max Threshold",
            "minimum": 50,
            "maximum": 100
        }
    },
    "required": [
        "closed_loop",
        "speed_decrease_set_point",
        "temperature_max_threshold"
    ]
}

The defaults/system section is [optional] and can be used to set different system requirements/constraints within the Docker App's running environment. i.e. Resources, Environment Variables, Volumes, Ports, etc:
app.yaml Example
1 2 3 4 5 6 7
defaults: system: ports: [] resources: {} environment_vars: [] volumes: [] privileged: Boolean

The defaults\system\ports is where you can define ports to open on the container to the local network:

app.yaml Example
defaults:
  system:
    ports:
      - name: http
        type: host
        host:
            port: 1880

      - name: opcua
        type: service # Exposed as a service for other containers
        service:
          port: 48010
          exposed_port: 30120

The defaults\system\resources is where you want to limit resources a container can use. This defines the reserved (requests) and limits the resources allocated to the Docker App:

app.yaml Example
defaults:
  system:
    resources:
      requests:   # Reserved
        cpu: 100m
        memory: 256Mi
      limits:     # Limits
        cpu: 200m
        memory: 512Mi

The defaults\system\environment_vars is used to define Environment Variables available within the Docker App container. i.e.:
app.yaml Example
1 2 3 4 5
defaults: system: environment_vars: - name: KELVIN_GW_MODE value: SOCKETS
Info

KELVIN_GW_MODE is an Environment Variable that is [required] by Kelvin's platform. Others can optionally be added.

The defaults\system\volumes is to share and persist data generated by Kelvin SmartApps™ or used by it in a specific place. They act like a shared folder between the Docker App and the host. Kelvin supports directory volumes, such as folders or serial ports, persistent, and file/test volumes:

app.yaml Example
defaults:
  system:
    volumes:
      # Folder Volume
      - name: serial-rs232
        target: /dev/rs232 # Container path
        type: host
        host:
          source: /dev/ttyS0 # Host path

      # Persistent Volume
      - name: extremedb
        target: /extremedb/data
        type: persistent

      # File/Text Volume
      - name: model-parameters
        target: /opt/kelvin/data/parameters.bin
        type: text # Renders data into a file
        text:
          base64: true
          encoding: utf-8
          data: |-
              SGVsbG8gUHJvZHVjdCBHdWlsZCwgZnJvbSB0aGUgRW5naW5lZXJpbmcgR3VpbGQhCg==

The defaults\system\privileged is [optional] and used to grant extended privileges to Kelvin SmartApps™, allowing it to access any devices on the host, such as a Serial device:
app.yaml Example
1 2 3
defaults: system: privileged: false
The defaults\configuration are the default global Docker App configuration values.

Note

Operations will have the option to change these at runtime from the Kelvin UI.
app.yaml Example
1 2 3 4
defaults: configuration: broker-ip: edge-mqtt-broker broker-port: 1883

The Dockerfile is a script used to define the instructions and configuration for building a Docker image. It specifies the base image, installation of software, file copying, and other setup tasks needed to create a reproducible and isolated environment for running Kelvin SmartApps™ in Docker containers.

For example if you wanted to create a basic Node Red Server for deployment to the edge, your Dockerfile can look something like this;

Dockerfile Example
FROM nodered/node-red