Developer Guide
App Bundle Structure
Each app has to be bundled as a zip archive (commonly used with suffix .wave
)
consisting of:
app.toml
- the platform configuration filestatic/
- static asset directory, including the app icon (a png file starting withicon
) and screenshots (files starting withscreenshot
)requirements.txt
- pip-managed dependencies of the app (can contain references to.whl
files included in the.wave
using paths relative to the archive root)- app source code
You can quickly create a .wave
archive by running h2o bundle
in your app git repository
(see the CLI section)
app.toml
Each app archive has to contain a app.toml
configuration file in the TOML format,
placed in the root of the .wave
archive, example:
Required attributes:
App
Name
- a machine-oriented unique identifier of the app (links different app versions together)Version
- a https://semver.org version of the app
Runtime
Module
- the name of the main Python module of the app, i.e., the app should be started viapython3 -m $module_name
Optional attributes:
App
Title
- a human-oriented name of the app for presentation in UI/CLI; stringDescription
- a multiline description of the app for presentation in UI/CLI; stringCategory
- category for organizing apps into groups, string (UI recognizesAll
,Data Science
,Financial Services
,Healthcare
,Insurance
,Manufacturing
,Marketing
,Retail
,Sales
,Telecommunications
, andOther
)Keywords
- keywords for search in the UI/CLI, list of strings
Runtime
VolumeMount
andVolumeSize
- request for a volume to persist app instance data across restarts,VolumeMount
has to be an absolute path,VolumeSize
needs to conform to the k8s resource model.ResourceVolumeSize
- request for a volume to persist internal app resources (such as Python venv) across restarts, only recommended for production-quality apps with sizeable resources due to cluster node limits, needs to conform to the k8s resource model.MemoryLimit
andMemoryReservation
- memory requirements for an instance of the app (default to service-wide settings managed by Admins); be conservative with these limits;MemoryLimit
is a hard limit on the maximum amount of memory an instance can use before it is OOM-killed;MemoryReservation
is how much memory is required to schedule an instance of the app.
Env
- request for a literal value/secret to be injected into an instance at startup-time as an Env variable; repeated; see Utilizing Secrets.Name
- name of the Env variable to the injected into the Python process; names prefixed withH2O_CLOUD
are disallowed.Secret
- name of the shared secret to use; each secret can contain multiple key-value pairs; cannot be used together withValue
.SecretKey
- name of the key within the secret to use; cannot be used together withValue
.Value
- the literal value of the Env variable; cannot be used together withSecret
/SecretKey
.
File
- request for a literal value/secret to be injected into an instance at startup-time as a file; repeated; see Utilizing Secrets.Path
- path to inject the file to; relative path means relative to the directory with the app code as determined by the platform; path dir cannot be/
or.
(only subdirs are allowed); path dir has to be unique across all otherFile
configurations; path dir/resources
is disallowed.Secret
- name of the shared secret to use; each secret can contain multiple key-value pairs; cannot be used together withValue
.SecretKey
- name of the key within the secret to use; cannot be used together withValue
.Value
- the literal value of the file; cannot be used together withSecret
/SecretKey
.
Runtime Environment
The platform configures the app instance runtime environment, i.e., OS, OS dependencies, location of the app code/venv, etc.
Developers can specify the pip-managed dependencies of the app via requirements.txt
(can contain
references to .whl
files included in the .wave
using paths relative to the archive root)
Developers can further customize the runtime environment by Utilizing Secrets.
note
At this moment, the platform does not provide any provisions for developers to customize the OS, native OS dependencies, Qd version, etc.
We are actively working on improving this.
CLI
As a developer, you will need the h2o
binary to interact with the platform.
Configuring the CLI
First you need to configure the CLI by running h2o config setup
so that it knows how to talk
to a particular platform deployment.
Be aware, currently the CLI launches a browser to complete the user authentication, and due to this we currently unable to support remote use of the CLI over SSH without provisions for X forwarding.
Listing existing apps
The h2o app list -a
command will list all apps available for launch.
Launching existing apps
To launch an app, the h2o app run <appId>
command can be used to launch a new instance of that app.
The -v
flag can be used with app run
to specify app instance visibility settings.
Publishing an app for others to see and launch
Just run h2o bundle import
in your app git repository. This will automatically package your
current directory into a .wave
package and import it into the platform.
If you set the visibility to ALL_USERS
(via the -v
flag), others will be able use h2o app run
or the UI to launch the app.
Note: the name-version combination from your app.toml
has to be unique and the platform will reject
the request if such combination already exists. Therefore, you need to update the version in app.toml
before each run.
Running an app under development
Just run h2o bundle deploy
in your app git repository. This will automatically package your
current directory into a .wave
package, import it into the platform, and run it.
In the output you will be able to find a URL where you can reach the instance, or visit the "My Instances" in the UI.
Note: the CLI will auto-generate the version so that you can keep executing this without worrying about version conflicts, just don't forget to clean up old instances/versions.
Getting the logs of a running app instance
Just run h2o instance logs
, use the flag -f
(--follow
) to tail the log.
Running the app in cloud-like environment locally
Just run h2o exec
. This will bundle the app in a temporary .wave
and launch it locally
using our platform docker image.
Note that this requires that you have docker installed and that you have access to the docker image.
Then navigate to http://localhost:55555/<your main route>
.
Updating App Visibility
The h2o app update <appId> -v <visbility>
command can be used to modify an existing app's visibility.
Authors who publish a new version of an app may want to de-list the old version. It is not possible
to remove an app if there are instances running, as the data may still need to be available.
The preferred method to de-list previous versions is to modify the visibility setting to PRIVATE
.
Updating Instance Visibility
The h2o instance update <instanceId> -v <visbility>
command, much like the app
version,
can be used to modify an existing running instance's visibility setting.
Managing App Tags
Tags are means of visually annotating apps in the platform (similar to GitHub issue labels).
The h2o tag [assign, get, list, remove, update]
commands let users see and, when authorized,
manage available app tags.
App tag configuration includes of name/title, RGB color, description, and ACLs.
Tags can only be assigned/removed/updated by user having a role (as determined by the auth provider)
present in the tag's Admin Roles
list (empty means any user).
Currently, tags can only be created and deleted by platform admins.
How-To
Updating App To a Newer Version
The "Catalog" page shows apps with visibility ALL_USERS
, so rolling out a new app version is done by:
- importing a new version of the app as
PRIVATE
- testing the new version
- changing the visibility of the new version to
ALL USERS
- (optional) changing the visibility of the old version to
PRIVATE
This is based on the Basic Concepts:
Apps are mostly immutable, meaning once uploaded, they cannot be changed (except for visibility). To "update" an app, one has to upload a new version.
and:
Internally, H2O AI Cloud treats every app name/version combination as a separate entity. The UI then uses the app name to link several versions together; however each can have different title, description, owner, instances, etc.
An important corollary is that instances of the old app version are not affected by the update (as they are completely separate from the new app version). The update only prevents users from starting new instances of the old version.
Utilizing Secrets
Developers can pass secrets registered with the platform to apps, exposed as environment variables
using the [[Env]]
section within the app.toml
or as files using the [[File]]
section.
This allows developers to link their apps with external dependencies (e.g., S3, Driverless AI) securely, while allowing easy overrides for local development or deployments outside the platform.
note
There is currently not a self-service option for developers to add their own secrets, nor is there an API for listing the available secrets. Secrets are currently managed by Admins. Contact your admins for the available secrets or for adding a new one.
We are actively working on improving this.
App Route
While it is not a strict requirement, since the platform deploys each app with its own Wave server,
we advise that apps use /
as their main route: