Skip to content

App Collection

Introduction

Simply put, an App Collection is a container of applications that belongs to one or multiple administrator (admin) users. These applications are available to all users that are subscribed to the collection. In order to deploy and share applications with other users you need to be an admin of at least one Collection.

However, this doesn't mean you can't build new applications without owning a Collection! You can use the Compute Engine to start a local collection and build apps from there. If you wish to share the app with other users, you just need to contact one of the admin users of the Collection you're looking to deploy and ask them to upload your application.

Locally, a Collection is represented as a directory in your machine. This directory has the following structure:

<name-of-app-collection>/
├── collection_requirements.yaml
├── apps
│   ├── my_app_dir
│   │   ├── local_image.png
│   │   ├── local_module.py
│   │   ├── app_meta.yaml
│   │   ├── README.md
│   │   └── my_app.py
│   └── my_other_app_dir
│   │   ├── app_meta.yaml
│   │   ├── README.md
│       └── my_other_app.py
├── shared
│   ├── shared_image.png
│   └── shared_module.py
└── typings

Files and Directories

Let's explore each one of these sections:

  • collection_requirements.yaml: This yaml file is responsible to map the requirements and settings of each application. Between these requirements is the entry python file, class name and root directory of your apps, local and shared resources, imported apps and app permissions.

  • apps/: The directory to save applications. Please note that all app directories must be located inside this directory.

  • apps/my_app_dir/: Each application must have a dedicated folder (such as my_app_dir), preferably with a name similar to the application's title. You can have multiple app entry modules in one app directory.

  • apps/my_app_dir/my_app.py: This is the entry python file to your application that we defined earlier in collection_requirements.yaml. Inside of this file, must be a class with the same name you defined in collection_requirements.yaml for this entry file. This class must inherit from AppStageCompute and implement all the required methods to build an app.

  • shared/: Use this directory to store shared static files and python modules that can be loaded across all the applications in the Collection.

  • typing/: Please don't delete or make any changes to this directory. It's used in several IDE's, such as vscode to provide you with code-completion and type-hinting when developing applications.

Requirements file

The collection_requirement.yaml file acts as a configuration file for your Collection, where you specify which apps to load and deploy, privileges and external files or modules to load.

Below is an example of this file:

apps_to_publish:
  - app_dir: my_app_dir
    entry_class: MyApp
    entry_module: my_app
    app_image:
      filepath: app_banner.png
      is_shared: false
    local_imports:
      modules:
        - local_module
      static_files:
        - local_image.png
    permissions:
      admin:
        - view
        - download
      member:
        - view
        - download
    shared_imports:
      modules:
        - shared_module
      static_files:
        - shared_image.png
    additional_apps:
      - MyOtherApp

The file must always have a root named apps_to_publish, where each item defines an app. Each app can be configured using the following keys:

app_dir

Name of the root directory of the app. Must be inside the apps/ folder.

entry_class

Name of the app's entry class.

entry_module

Name of the app's entry python module.

app_image [Optional]

Use this field to define an image for the app. This field takes 2 parameters:

  • filepath: The dotted filepath to the image.
  • is_shared: Whether the filepath is located in the app directory specified in app_dir or in the shared directory.

Warning

Each image can have a maximum of 200 KB, and must have one of the following extensions: .png, .jpg, .jpeg, .webp or .svg.

Tip

For better rendering, consider using 350x175 (px) images, or images with a 1:2 height:width ratio.

local_imports [Optional]

Here you can add any external python module under modules and any static files (images, csv files, etc) under static files.

Note

If you wish to create sub-folders, use the dotted notation to specify the path to the file (e.g. if you have a filepath my_app_dir/resources/an_image.png, you should use resources.an_image.png) .

Note

Filepaths are always in relation to the app's root directory.

shared_imports [Optional]

Same as local_imports, but these files can be shared across all applications in the collection whereas the ones defined under local_imports are only accessible to the respective app's directory.

permissions [Optional]

Define view and download permissions of your apps. By default, admin has permission to view and download, and member has only permission to view.

additional_apps [Optional]

If your app imports another app (e.g. by running exec_app), then you need to specify each imported app's entry class name under this field. Please note that any imported app must also be configured in this collection_requirements.yaml file.