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
application
Denotes the version of this document. Supported values are:
"v1"
title
title
User friendly title for the tool.
name
and version
name
and version
The name
and version
is a combination which uniquely identifies this document.
authors
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
description
A markdown description of this tool.
tags
tags
A list of tags for this application. Used only for discoverability.
applicationType
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 theweb
block to be defined.VNC
: An interactive application accessed via VNC. Requires thevnc
block to be defined.
allowAdditionalMounts
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
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
allowMultiNode
Controls if the application should allow multiple nodes to be used.
invocation
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
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
Would invoke the following command: foo bar 42
.
type: var
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 ifprefixVariable
should be part of the same argument as the variable. Default:false
.isSuffixVariablePartOfArg
: A boolean to determine ifprefixVariable
should be part of the same argument as the variable. Default:false
.
Examples
Simple example:
With var = "hello"
would cause the following invocation: foo hello
.
Multiple variables:
With var1 = "v1", var2 = "v2"
would cause the following invocation foo v1 v2
.
Simple global prefixes:
With var1 = "v1", var2 = "v2"
would cause the following invocation foo --flag v1 v2
.
Simple variable prefixes:
With var1 = "v1", var2 = "v2"
would cause the following invocation foo --flag v1 --flag v2
.
isPrefixVariablePartOfArg example:
With var1 = "v1", var2 = "v2"
would cause the following invocation foo --flagv1 --flagv2
.
Prefixes and Suffixes:
With var1 = "v1", var2 = "v2"
would cause the following invocation foo --gloPre --pre v1 --suf --pre v2 --suf --gloSuf
.
type: flag
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 ofvar
is true
Examples
Simple Example:
With var1 = true
would cause: foo --do-this-thing bar
.
With var1 = false
would cause: foo bar
.
parameters
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 withoptional: true
.title
: (Optional) A user friendly title for the parameter. Defaults to be the same asname
.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
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
type: input_directory
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
type: text
type: text
A simple text value. Will be passed as a single invocation parameter (multiple words are supported).
Examples
Simple:
With default value:
type: integer
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 havemax
: (Optional) The maximum value this parameter can havestep
: (Optional) Integer value determining how big the 'steps' should be in the slider UI component. Only useful whenmin
andmax
is specified.unitName
: (Optional) An optional unit name to be displayed in the UI.
Examples
Simple:
With default value:
Percentages:
Distances:
type: floating_point
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
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:
With default value:
Different values:
Different values (2):
With my_parameter = true
will cause invocation foo --my-flag 1
.
type: enumeration
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:
With default value:
type: peer
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:
type: license_server
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
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
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 applicationThe 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
Matches all files that ends on .txt
and all files named Makefile
, but not files that ends on Makefile
(i.e. hello.Makefile
).
outputFileGlobs
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
In directory:
Would transfer the following files:
container
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 istrue
.runAsRoot
: Should this container be forcefully be changed to run as root? By default we will respect the containers configuration. Default value isfalse
.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 isfalse
.
Examples
Always run this container as root:
environment
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
type: env
Used for aliasing of environment variables.
var
: The variable to alias
Examples
Simple example:
Variable aliasing:
Environment variables from user input:
vnc
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:
web
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.
Last updated