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 entrypython
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 multipleapp 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 incollection_requirements.yaml
. Inside of this file, must be a class with the same name you defined incollection_requirements.yaml
for this entry file. This class must inherit fromAppStageCompute
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 theCollection
. -
typing/: Please don't delete or make any changes to this directory. It's used in several
IDE
's, such asvscode
to provide you withcode-completion
andtype-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 theapp
directory specified inapp_dir
or in theshared
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.