Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

Prerequisites

Before we start, make sure you have everything installed. You’re going to need:

  • node js

  • ombori grid client command-line utility

  • docker 

  • a credentials to your own docker image registry

  • a grid-os device up and running

Creating a project

Now, let’s bootstrap our module. Run this command in terminal

omg module create hello

This will create a new folder named hello with basic nodejs module structure in it. 

Let’s have a look at file structure: 

  • package.json - a nodejs module file description in JSON format. A name field from this file will be used as a module name.

  • settings.json - container settings file, a settings.createOptions field from this file will be used to set up the container. This can be used to specify container port binding, volumes and other container options.

  • module.json - module settings file, an image.repository field from this file specifies the repository where the module image will be stored. Also image.tag.version stores the current image version. This value will be auto-increased when doing image build (see “Building” section below)

  • Dockerfile.amd64 - a dockerfile with instructions on how to build module image for amd64 platform

  • Dockerfile.arm32v7 - a dockerfile with instructions on how to build module image for arm32 platform

  • schema.ts - schema file for settings that will be displayed for this module on a device configuration page

  • src/app.js - module entry point

Before building our image we need to specify a correct docker image name and repository. Assuming you image will be stored at my-docker-repo.azurecr.io/my-image and credentials for this container registry are “username” and “password”, you’ll need to do the following:

Update repository value in the module.json file

{ 
   "$schema-version": "0.0.1",
   "description": "",
   "image": {
       "repository": "my-docker-repo.azurecr.io/my-image",
       "tag": {
           "version": "0.0.1",
           "platforms": {
               "amd64": "./Dockerfile.amd64",
               "arm32v7": "./Dockerfile.arm32v7"
           }
       },
       "buildOptions": []
   },
   "language": "javascript"
}

Now create a file with the name .env in the repo root folder:

my-docker-repo.azurecr.io_USERNAME=username
my-docker-repo.azurecr.io_PASSWORD=password

This file will contain credentials for your container registry. Note that this file is not saved in .git to prevent credentials being stored in version control.

Now your module is ready to be built.

Building and deploying

To build the module just run yarn build in your terminal. This command does the following:

  • it checks if a local image is created for this module

  • if the repo contains any commits newer than the local image, a minor version of the module will be bumped and a new docker image will be built.

  • otherwise if the repo contains any uncommitted changes, newer than local image, a patch version of the module will be bumped and a new docker image will be built.

  • if the repo does not contain any changes, nothing will be done

In other words, for each change in your local files, a new image will be built and a patch version of the image will be increased: 0.0.1 -> 0.0.2 -> 0.0.3 etc. After you commit your changes, a minor version will be bumped instead: 0.0.3->0.1.0. 

Now, before you push your new module to the device you’ll need to build the settings schema for it. Settings schema is a specification for the form that will be displayed in a list of modules on the device configuration page.

yarn schema

Now after the settings are built, it is time to deploy your module.

First, you’ll need to know your device name. Device names have org-name.device-name format. To see all devices available for you, run omg dev list. Lets assume your device name is acme.my-device.

Now that you know your device name, run this command:

omg module deploy acme.my-device

The module is now saved in the device configuration, along with its configuration files and settings schema. Note that the module is not yet being installed on the device because it is not enabled yet. To enable the module, go to your device page in the grid console, find an entry for your new module, and click the ‘enabled’ checkbox. You can also specify additional parameters for the module.

Monitoring

Now, after you have enabled the module, it will be downloaded and started on the device. To monitor current status of the module run omg dev modules <devicename>. 

After the module has started you can see its logs using omg dev logs <devicename> <modulename>. 

You can also invoke module methods using omg dev invoke <devicename> <modulename> <method> ‘<payload>’.


  • No labels