Skip to content

Create a Docker App

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.

create default application
1
$ kelvin app create --app-type docker <EXPORT_NAME>

This will give a response similar to this;

command output
1
2
3
4
[kelvin.sdk][2025-09-02 04:22:27][I] Refreshing metadata..
[kelvin.sdk][2025-09-02 04:22:27][I] Creating new application "demodocker"
[kelvin.sdk][2025-09-02 04:22:27][R] Successfully created new application: "demodocker".
[kelvin.sdk][2025-09-02 04:22:27][I] Kelvin code samples are available at: https://github.com/kelvininc/app-samples

This will automatically create an Import Application bootstrap within a new directory and populated with some default files and configurations.

Folder Structure

You can now open the folder in your favorite IDE or editor and start to modify the files to create your Import Application.

default folder structure
1
2
3
4
5
6
7
$ cd demodocker
$ tree ./
├── .dockerignore
├── Dockerfile
├── app.yaml
└── ui_schemas
    ├── configuration.json

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 browser.

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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
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
    1
2
3
4
5
    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
    1
2
    ui_schemas:
  configuration: "ui_schemas/configuration.json"

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

    Note

    configuration.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/configuration.json
    1
2
3
4
5
    {
    "type": "object",
    "properties": {},
    "required": []
}

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

    Sample ui_schemas/configuration.json
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
    {
    "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
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
    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
    1
2
3
4
5
6
7
8
9
    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
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
    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

You use config.yaml to override default configurations defined in your app.yaml file during local development and testing.

Note

If there is no config.yaml or it is empty, then the app.yaml default configurations will be used in any local testing.

This file provides a secure way to manage sensitive data like credentials, API keys, and environment-specific settings without committing them to version control or uploading them to the cloud platform.

The configuration loading follows a strict hierarchy: config.yaml → app.yaml defaults → graceful failure.

Note

This ONLY takes precedence over the default/configurations section of the app.yaml during local testing.

All other sections in the app.yaml are not affected.

This ensures your SmartApp always prioritizes local overrides while falling back to safe defaults when appropriate.

The file itself will contain any hierarchy from the configurations key only.

If the app.yaml has this;

app.yaml default configurations example
1
2
3
4
5
6
7
8
9
# app.yaml
defaults:
  configuration:
    threshold: 50.0
    interval: 60
    mqtt:
      host: <% secrets.mqtt_host %>
      username: <% secrets.mqtt_username %>
      password: <% secrets.mqtt_password %>

Then the local config.yaml will look like this;

Note

In this example we have also added sensitive mqtt information that will not be incorporated in the upload to the Kelvin Platform.

config.yaml for local testing
1
2
3
4
5
6
7
8
# config.yaml
threshold: 75.0
interval: 30
mqtt:
  host: "localhost_from_config"
  username: "user_from_config"
  password: "password_from_config"
debug_mode: true

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
1
FROM nodered/node-red