Applications¶

Applications are described by YAML documents. The document describes the parameters of an application and how these should be used to invoke it. Each application has an associated tool.

TODO Application environment variables, working directory, …

Reference¶

`application`¶

Denotes the version of this document. Supported values are:

"v1"

`title`¶

User friendly title for the tool.

`name` and `version`¶

The name and version is a combination which uniquely identifies this document.

`authors`¶

A list of authors (strings). The list of authors can be anything and doesn’t have to conform to any standard. This is used solely for giving credit to the authors.

`description`¶

A markdown description of this tool.

`tags`¶

A list of tags for this application. Used only for discoverability.

`applicationType`¶

Denotes the type of application. Different application types behave in different ways. Supported values:

BATCH: A batch style application. It is run to completion without any user input.
WEB: An interactive application with a web interface. Requires the web block to be defined.
VNC: An interactive application accessed via VNC. Requires the vnc block to be defined.

`allowAdditionalMounts`¶

Controls if the application should allow additional folders to be mounted. This is the default for interactive applications. For batch applications this is by default false.

`allowAdditionalPeers`¶

Controls if the application should allow additional peers to be mounted. This is the default for interactive applications. For batch applications this is by default false.

`allowMultiNode`¶

Controls if the application should allow multiple nodes to be used.

`invocation`¶

A list of invocation ‘arguments’ which denote how the application should be started. Each item in the list translates to zero or more arguments on the command line.

`string`¶

If the item in the list is a string (or can be converted to one) then the invocation parameter will be passed as is.

Example¶

invocation:
- foo
- bar
- 42

Would invoke the following command: foo bar 42.

`type: var`¶

Puts one or more variables into the invocation. This invocation argument has several additional fields:

vars: A list of variable names (or a single string)
prefixGlobal: A global prefix. This will be added before any of the variables. This will be passed as its own argument.
suffixGlobal: A global suffix. This will be added after all of the other variables. This will be passed as its own argument.
prefixVariable: An argument to be passed with each variable.
suffixVariable: An argument to be passed with each variable.
isPrefixVariablePartOfArg: A boolean to determine if prefixVariable should be part of the same argument as the variable. Default: false.
isSuffixVariablePartOfArg: A boolean to determine if prefixVariable should be part of the same argument as the variable. Default: false.

Examples¶

Simple example:

invocation:
- foo
- type: var
  vars: my_variable

With var = "hello" would cause the following invocation: foo hello.

Multiple variables:

invocation:
- foo
- type: var
  vars:
  - var1
  - var2

With var1 = "v1", var2 = "v2" would cause the following invocation foo v1 v2.

Simple global prefixes:

invocation:
- foo
- type: var
  prefixGlobal: --flag
  vars:
  - var1
  - var2

With var1 = "v1", var2 = "v2" would cause the following invocation foo --flag v1 v2.

Simple variable prefixes:

invocation:
- foo
- type: var
  prefixVariable: --flag
  vars:
  - var1
  - var2

With var1 = "v1", var2 = "v2" would cause the following invocation foo --flag v1 --flag v2.

isPrefixVariablePartOfArg example:

invocation:
- foo
- type: var
  prefixVariable: --flag
  isPrefixVariablePartOfArg: true
  vars:
  - var1
  - var2

With var1 = "v1", var2 = "v2" would cause the following invocation foo --flagv1 --flagv2.

Prefixes and Suffixes:

invocation:
- foo
- type: var
  prefixGlobal: --gloPre
  suffixGlobal: --gloSuf
  prefixVariable: --pre
  suffixVariable: --suf
  vars:
  - var1
  - var2

With var1 = "v1", var2 = "v2" would cause the following invocation foo --gloPre --pre v1 --suf --pre v2 --suf --gloSuf.

`type: flag`¶

Used to represent boolean flags. This is used in combination with a parameter of type boolean. This invocation argument has the following additional fields:

var: The variable. This must point to a variable of type boolean.
flag: The value to include if the value of var is true

Examples¶

Simple Example:

invocation:
- foo
- type: flag
  var: var1
  flag: --do-this-thing
- bar

With var1 = true would cause: foo --do-this-thing bar.

With var1 = false would cause: foo bar.

`parameters`¶

Applications parameters are an opportunity for users to pass in their own input. Each parameter define the format of a single piece of information. The following fields are shared for all parameters:

type: The type of application parameter (see below).
optional: (Optional) Specifies if this value is optional.
defaultValue: (Optional) The default value for this parameter. Only makes sense to use with optional: true.
title: (Optional) A user friendly title for the parameter. Defaults to be the same as name.
description: (Optional) A user friendly description of the parameter. Markdown is supported.

Note: A parameter can be optional without a defaultValue. In this case no arguments will be passed to the invocation.

`type: input_file`¶

Represents an input file from UCloud. When passed to an invocation it will be converted into the absolute path to the file. The input file will be mounted at the working directory with the same name as in UCloud.

defaultValue for this type is not supported.

Examples¶

invocation:
- foo
- type: var
  vars: my_parameter

parameters:
  my_parameter:
    type: input_file

`type: input_directory`¶

Represents an input directory from UCloud. When passed to an invocation it will be converted into the absolute path to the file. The input file will be mounted at the working directory with the same name as in UCloud.

defaultValue for this type is not supported.

Examples¶

invocation:
- foo
- type: var
  vars: my_parameter

parameters:
  my_parameter:
    type: input_directory

`type: text`¶

A simple text value. Will be passed as a single invocation parameter (multiple words are supported).

Examples¶

Simple:

parameters:
  my_parameter:
    type: text

With default value:

parameters:
  my_parameter:
    type: text
    optional: true
    defaultValue: "myDefaultValue"

`type: integer`¶

An integer value. This will be passed as a single invocation parameter. Internally big integers are used for storing. The following additional fields can be used:

min: (Optional) The minimum value this parameter can have
max: (Optional) The maximum value this parameter can have
step: (Optional) Integer value determining how big the ‘steps’ should be in the slider UI component. Only useful when min and max is specified.
unitName: (Optional) An optional unit name to be displayed in the UI.

Examples¶

Simple:

parameters:
  my_parameter:
    type: integer

With default value:

parameters:
  my_parameter:
    type: integer
    optional: true
    defaultValue: 42

Percentages:

parameters:
  my_parameter:
    type: integer
    min: 0
    max: 100
    unitName: "%"

Distances:

parameters:
  my_parameter:
    type: integer
    min: 0
    max: 1000
    step: 5 # Any value can still be used between 0-1000
    unitName: "meters

`type: floating_point`¶

A floating point value. Internally a big decimal type will be used. Uses the exact same interface as type: integer.

`type: boolean`¶

A boolean value with configurable values for true and false. Will be passed as a single argument. Additional fields are possible:

trueValue: (Optional) A different value to be passed is the input is true. Default: "true".
falseValue: (Optional) A different value to be passed is the input is false. Default: "false".

Examples¶

Simple:

parameters:
  my_parameter:
    type: boolean

With default value:

parameters:
  my_parameter:
    type: boolean
    optional: true
    defaultValue: true

Different values:

parameters:
  my_parameter:
    type: boolean
    trueValue: --yes-do-this-thing
    falseValue: --no-do-this-other-thing

Different values (2):

invocation:
- foo
- --my-flag
- type: var
   vars: my_parameter

parameters:
  my_parameter:
    type: boolean
    trueValue: "1"
    falseValue: "0"

With my_parameter = true will cause invocation foo --my-flag 1.

`type: enumeration`¶

An enumeration. A simple enumeration value, uses fixed input options. Both name and value in the options are strings. Internally similar to a text parameter.

Examples¶

Simple:

parameters:
  shell:
    type: enumeration
    options:
      -
        name: Bash
        value: "0"
      -
        name: Zsh
        value: "1"

With default value:

parameters:
  shell:
    defaultValue:
      type: enumeration
      value: "1"
    options:
      -
        name: Bash
        value: "0"
      -
        name: Zsh
        value: "1"

`type: peer`¶

A peer is a different application which this application should ‘connect’ to. This means that a hostname entry will be created.

Additional fields:

suggestedApplication: (Optional) The name of an application that this application should connect to. This must match the name and not the title of the application!

Examples¶

Simple example:

parameters:
  spark_cluster:
    type: peer
    suggestedApplication: spark

`type: license_server`¶

License servers are for internal authorization by an application. License servers can be administered using the Admin page, and tagged with optional keywords. The license_server parameter can then be used to make license servers available for selection by keywords.

An Access Control List exists for every license server. Permissions for a license server needs to be explicitly set for each user.

Examples¶

invocation:
- type: var
  vars: my_license_server
parameters:
  my_license_server:
    title: "A license server is required, pick one"
    type: license_server
    tagged: [figlet-server]

The user will be prompted to select any license server with the tag figlet-server, which the user has access to according to each license server ACL.

The details of the license server is hidden from the user. When the job is started, the details of the selected server will be fetched and passed as an invocation parameter.

Ultimately it is up to each application to handle the license server information while the job is running (that is, authorization etc.).

`fileExtensions`¶

A list of file extensions supported by this application.

An application is capable of opening a file if it meets the following requirements:

The application only has optional parameters
The application is interactive (web or VNC)
The extension of the file is in the list of fileExtensions of the application
The application is in the user’s favorite list

The list of file extensions are represented as strings. A file extension which starts with “.” will match any file which ends with the extension. A file extension which does not start with “.” will only match files with names that are equal to the extension.

Upon quick launch of a application on a file, the application will be mounted with default settings, with the parent directory of the file mounted.

Examples:¶

“Dockerfile”: Matches files called “Dockerfile” and nothing else
“.zip”: Matches any file ending in “.zip”
“.tar.gz”: Matches any file ending in “.tar.gz”
“hello.txt”: Matches files called “hello.txt” and nothing else

fileExtensions:
  - ".txt"
  - "Makefile"

Matches all files that ends on .txt and all files named Makefile, but not files that ends on Makefile (i.e. hello.Makefile).

`outputFileGlobs`¶

A list of globs to capture relevant output files. All globs will be executed in the working directory and evaluated against the file name of each file in the working directory. If a folder is captured it will be copied as is.

Examples¶

outputFileGlobs:

- *.txt
- file.png
- folder

In directory:

.
├── a.png
├── b.png
├── c.txt
├── d.txt
├── file.png
└── folder

Would transfer the following files:

├── c.txt
├── d.txt
├── file.png
└── folder

`container`¶

Optional.

Specifies some additional configuration for how the container should work. This can be passed for any application type. The following fields are defined:

changeWorkingDirectory: Should the working directory be changed to /work/. Default value is true.
runAsRoot: Should this container be forcefully be changed to run as root? By default we will respect the containers configuration. Default value is false.
runAsRealUser: Should this container be forcefully be changed to run as the UID matches the UCloud UID? By default we will respect the containers configuration. Default value is false.

Examples¶

Always run this container as root:

container:
  runAsRoot: true

`environment`¶

Optional.

An object containing environment variable keys and invocation arguments as their values. These environment variables will be available inside of the container.

In addition to the arguments listed in the invocation section we can use the following invocation argument:

`type: env`¶

Used for aliasing of environment variables.

var: The variable to alias

Examples¶

Simple example:

environment:
  var1: my_value

Variable aliasing:

environment:
  var1: my_value
  var2:
    type: env
    var: var1

Environment variables from user input:

parameters:
  my_parameter:
    type: text

environment:
  envVar1:
    type: var
    vars: my_parameter

`vnc`¶

Used with applicationType: VNC.

This block configures how to access the VNC server running inside of the container. The VNC server running inside of the container is required to support VNC via websockets. Additionally the server should run with no password or a pre-configured password which should be passed in this block.

Note: All authentication is done by UCloud, hence we do not need to rely on the security of VNC.

The following fields are supported in this block:

password: (Optional) The password for this VNC server. Default value is none.
port: (Optional) The port inside of the container that the server will respond to VNC websocket traffic. Default is 5900.

Examples¶

Simple:

vnc:
  password: hardcodedPassword
  port: 5902

`web`¶

Used with applicationType: WEB.

This block configures how to access the web server running inside of the container. Just like with applicationType: VNC authentication should generally be disabled for the web application. Authentication will automatically be done by UCloud.

UCloud will proxy traffic as HTTP to the webserver running inside of the container.

The following fields are supported in this block:

port: (Optional) The port to access the web server inside of the container. Default value is 80.

Applications¶

Reference¶

application¶

title¶

name and version¶

authors¶

description¶

tags¶

applicationType¶

allowAdditionalMounts¶

allowAdditionalPeers¶

allowMultiNode¶

invocation¶

string¶

Example¶

type: var¶

Examples¶

type: flag¶

Examples¶

parameters¶

type: input_file¶

Examples¶

type: input_directory¶

Examples¶

type: text¶

Examples¶

type: integer¶

Examples¶

type: floating_point¶

type: boolean¶

Examples¶

type: enumeration¶

Examples¶

type: peer¶

Examples¶

type: license_server¶

Examples¶

fileExtensions¶

Examples:¶

outputFileGlobs¶

Examples¶

container¶

Examples¶

environment¶

type: env¶

Examples¶

vnc¶

Examples¶

web¶

`application`¶

`title`¶

`name` and `version`¶

`authors`¶

`description`¶

`tags`¶

`applicationType`¶

`allowAdditionalMounts`¶

`allowAdditionalPeers`¶

`allowMultiNode`¶

`invocation`¶

`string`¶

`type: var`¶

`type: flag`¶

`parameters`¶

`type: input_file`¶

`type: input_directory`¶

`type: text`¶

`type: integer`¶

`type: floating_point`¶

`type: boolean`¶

`type: enumeration`¶

`type: peer`¶

`type: license_server`¶

`fileExtensions`¶

`outputFileGlobs`¶

`container`¶

`environment`¶

`type: env`¶

`vnc`¶

`web`¶