JARVICE Application Definition Guide

The JARVICE Application Definition (AppDef) Reference describes the application interface for applications that are deployed on JARVICE with PushToCompute™.

The JARVICE Application Definition (AppDef) is a simple JSON object which is used to define:
  • The work flow (commands, data and parameters)
  • The user interface (the Task Builder web form, and an API schema)
  • Validation rules for the automatically generated API to run this application
  • The command line entry point into the JARVICE Nimbix Application Environment (NAE).

By using a simple, declarative JSON object, the AppDef makes designing work flows and user experiences easy on JARVICE. No prior experience designing web interfaces or APIs is required to deploy a multi-node high performance computing application which leverages the built-in capabilities of JARVICE on the Nimbix Cloud.

Example

TensorFlow AppDef Example
TensorFlow Task Builder

General Application Information Fields

Field Name Type Required/Optional Description
Environment and Configuration
commands command (object) required Defines an application command in the application drop down.
variables variable (object) optional Defines user and application-defined environment variables which will be available in /etc/JARVICE/jobenv.sh. This can be overridden in a command that is defined in the “commands” section.
Storage and Machine Options
machines list of strings or REGEX required Machines can be any machine type available on Nimbix, or accepted lazy expansions. For example, ng* would make all GPU machine types available for this application. This can be overridden in a command that is defined in the “commands” section.
scale_max integer optional Defines the maximum number of machines allowed for this application. This can be overridden in a command that is defined in the “commands” section.
vault-types list of strings required

For no vault requirements, this should be

“vault-types”: [ “NONE” ]

Defines what storage vaults are supported by the application. Must be one or more of of:

“BLOCK”, “BLOCK_ARRAY”, “FILE”, or “NONE”

The default distributed file storage vault, drop.jarvice.com, is a FILE vault.

Catalog Information
name string required Defines the human-readable name of the application.
description string required Description of the application used in the application market place icon.
author string required Name of the individual or company who authored the application.
licensed boolean required Defines whether the application requires an additional license. false = Application needs a third party license in order to run. true = Application pricing includes on-demand license costs or has no additional license fees.
classifications string required Defines the categories used for sorting and searching applications.
image image (object) required Defines the application icon.

Object Reference in the Application Definition Format

Name Type Required/Optional Description
Image
data string  required Base64 image data. This can easily be generated with:
cat image.png | base64 -w0 > image.base64Alternatively, the image can be uploaded directly in the Apps section of the portal.
type string  required This identifies the media type, e.g., “image/png”
Commands
Commands are named by the key of the JSON object defining the command.
path string required Command entry point which is run in the Nimbix Application Environment when the application starts. For a graphical application, this could be “/usr/local/bin/nimbix_desktop /usr/bin/xterm”

For a batch application, this could be the path to a batch script.

name string required Command’s name, which is used as the title of the command in the application’s catalog entry.
description string required Description of the command’s functionality that is used in the application’s catalog entry.
interactive boolean optional If true, a public IP address and host name is assigned to the NAE when it is launched. This should be true for any application using the Nimbix Desktop, as well as any application which provides SSH or HTTP access.
parameters parameter (object)  Parameters are used to construct the arguments passed to the command identified by the “path” key of the command argument.
machines list of strings optional Machines can be any machine type available on Nimbix, or accepted lazy expansions. For example, ng* would make all GPU machine types available for this application. Including machines in this section overrides the machines defined in the “commands” section.
variables variable (object) optional Defines user and application-defined environment variables which will be available in /etc/JARVICE/jobenv.sh.
Parameters
Parameters are used to construct the arguments passed to the command identified by the “path” key of the command argument.
name string required Name of the parameter (used in the Task Builder).
description string required Description of the parameter (used in the Task Builder).
type string required Identifies the type of the parameter. One of: “CONST”, “STR”, “INT”, “FLOAT”, “RANGE”, “BOOL”, “selection”, “FILE”
required boolean required
positional boolean optional True indicates the value of the parameter should be passed as a positional argument, ordered by the order of JSON objects in the parameters section.
(parameter dependent fields) varies by parameter type See the parameter definition table for fields required by parameter type.
Variables
Variables are designed to be used as environment variables that are written to /etc/JARVICE/jobenv.sh. The key of the variable becomes the name of the variable when the job is launched.
name string required Defines a human-readable name of the variable.
description string required Description of the variable.
userowned boolean required If true, then the user may override this value  . If false, it is an account variable which is currently managed and set by Nimbix Support.
inherit boolean required If true, the value of an account variable can be inherited from a team’s payer account.
required boolean optional If true, the application will not launch if the variable is not defined.

Parameter Type Documentation

Type Description Notes
CONST Constant value (not selectable by end user) “value” may be either arbitrary literal value, or substitution as follows:
  • %CORES% – number of CPU cores in machine
  • %GPUS% – number of GPUs in master node
  • %SGPUS% – number of GPUs in each slave node
  • %RAM% – amount of RAM in master node, in GB
  • %SRAM% – amount of RAM in each slave node, in GB
  • %NODES% – number of nodes selected
  • %TCORES% – total number of cores selected (%CORES% * %NODES%)
  • %TGPUS% – total number of GPUs selected (%GPUS% + (%SGPUS% * (%NODES% – 1)))
  • %TRAM% – total amount of RAM selected (%RAM% + (%SRAM% * (%NODES% – 1)))
  • %JOBLABEL% – job label, if specified
  • %VTYPE% – vault type (e.g. NONE, FILE, OBJECT, BLOCK, BLOCK_ARRAY)
STR String (default if “type” is not specified)
  • “value” is an arbitrary default value to populate, which the user can edit; this may also be blank
INT Integer
  • “value” is the default value (which can be left blank to require an explicit value set)
  • “min” is the minimum number
  • “max” is the maximum number
FLOAT Floating point value
  • “value” is the default value (which can be left blank to require an explicit value set)
  • “min” is the minimum number
  • “max” is the maximum number
  • “precision” is the maximum number of decimal digits allowed (values will be truncated to this)
RANGE Range of integers (GUI hint is slider bar)
  • “value” is the default value, which must be set
  • “min” is the minimum number
  • “max” is the maximum number
  • “step” is the number of steps of each increment
BOOL Boolean – represented as a checkbox in user interfaces
  • “value” is the default, which must be set to true or false; once submitted, if true, the parameter will be listed on the command line, or not listed if false
selection Selection list drop-down
  • “values” is a list of values; the default will be the first one listed; if empty string is submitted (and is a valid selection), the parameter will not be listed
  • “mvalues” is a parallel list of values in machine format; if specified, the index of “values” will be used to fetch the actual value to pass into the application from the “values” list; it must have the same exact dimension as the “values” list; if not specified, only the “values” list will be used
FILE File name
  • “value” is not valid here
  • “filter” is a list of wildcards to filter by (standard shell wildcard syntax); if there is more than one wildcard specified, use the | (vertical bar) to separate them