Links

App JSON config

Configuration that connects Python application with Supervisely

Introduction

The app config (config.json) is used for configuring how a project loads in Supervisely. All data is stored in app configuration as key-values, where keys are the string type and values must be in valid JSON format for Supervisely to process it correctly. Otherwise, app might fail. Configuration file must be located at the root of your project, next to the .env file.
Here is a bare-minimum example:
{
"name": "Hello World!",
"version": "2.0.0",
"entrypoint": "python -m uvicorn src.main:app --host 0.0.0.0 --port 8000"
}

Properties

The Supervisely app config configures many things such as app name, category, icon, poster, docker image and so on. A complete list of available properties with example values is described below. Don't worry, you don't need all of them.

name

Required property
Name of the app
"name": "Hello World"

description

App description in Ecosystem
"description": "Working demo, use it as a template for your custom apps

type

Specifies type of the Ecosystem entity. Default value is "app"
Types
Available types:
"type": "app"

categories

List of categories that app are associated with in Ecosystem. App can have as many categories as you like.
YOLOv5 app categories
"categories": [
"neural network",
"images",
"videos",
"object detection",
"detection & tracking",
"train"
]
List of main categories:
Main categories
Category tags combination
Main categories also contain sub-categories.
If you want your application to appear there you must combine multiple tags. Place order does not matter.
"categories": [
"images",
"annotation transformation",
"data operations"
]
List of sub-categories:
  • "images", "videos", "dicom", "pointclouds"
  • "object detection", "semantic segmentation", "instance segmentation", "classification", "interactive segmentation", "metric learning"
  • "detection & tracking", "segmentation & tracking", "interactive segmentation", "interpolation"
  • "annotation transformations", "data transformations", "modality transformations", "projects management", "composition & synthesizing", "augmentation"
  • "train", "serve"

icon

Link to the application icon. If not specified the first two letters of the app name will be displayed as an icon
"icon": "https://your-icon.png"

icon_cover

Stretches the icon to full width. Comparison of icon cover true (left) and false (right)
"icon_cover": false

icon_background

Icon background color in hex color code format
"icon_background": "#FFFFFF"

poster

Link to the application poster. If not specified displays icon as poster
Comparison of thumbnail with and without spcified poster
"poster": "https://your-poster.png"

version

Required property
App engine version. If you want to use legacy app engine do not specify version property.
"version": "2.0.0"

entrypoint

Required property
Instruction for executing app scripts v2.0.0 app engine only, for legacy apps use main_script property, but not both
src.main is a relative path to main.py which contains app object :app
"entrypoint": "python -m uvicorn src.main:app --host 0.0.0.0 --port 8000"
Note: if app object is in a different script file like globals.py, and globals.py is imported to main.py script you can specify it like src.main:globals.app

port

Use this property if you want to specify certain port (v2.0.0 app engine only)
"port": 8000

docker_image

Docker image used to run the app. If not specified uses supervisely/base-py-sdk image based on supervisely version in requirements.txt file or uses latest version. List of available supervisely docker images can be found at Dockerhub
"docker_image": "supervisely/base-py-sdk:6.68.6"

community_agent

Applicable only for Community Edition instances. Users of Enterprise Instances can ignore this field. If flag is False - then the app can not be run on public agents and has to be run only on user's agents. Default value is true.
Practical example: by default users of Community Edition can run apps on the agents (computers) provided by Supervisely team for free. If app, for example, deploys NN inside, Supervisely team can not allow community users to run this app due to the limitation of available GPU resources. That is why some resource-intensive apps have this flag: "community_agent": false
"community_agent": false

min_agent_version

Minimum agent version to launch app. Current agent version can be found at the Team Cluster page. List of available agent versions can be found at Dockerhub
"min_agent_version": "6.7.4"

min_instance_version

Minimum instance version to launch app. Current instance version can be found at the bottom right corner at the Supervisely
If the current instance version is lower than the version specified in the application, the supervisely platform will try to find a compatible instance version
"min_instance_version": "6.5.50"

instance_version

"instance_version": "6.5.50"

headless

Specifies if app do not use frontend. Set to false for the apps with GUI. Default value is false
"headless": true
Relative path to modal window template from project root
"modal_template": "src/modal.html"
Initializes default values for data variables in modal window
"modal_template_data": {
"test_1": "modalDataVal 1",
"files": null
}
Initializes default values for state variables in modal window
"modal_template_state": {
"checkbox_1": false,
"checkbox_2": true,
"input": ""
}

context_menu

App context menu configuration options. If not specified, app can be launched only from Ecosystem
context_category - sub section in context menu
target - determines where the application can be launched from
"context_menu": {
"context_category": "Import",
"target": ["files_folder", "images_project", "images_dataset", "agent_folder"]
}
files_folder/agent_folder
images_project/images_dataset
files_folder/agent_folder
images_project/images_dataset
List of available context menu targets:
  • "team"
  • "workspace"
  • "labeling_job"
  • "team_member"
  • "files_folder"
  • "files_file"
  • "agent_folder"
  • "agent_file"
  • "images_project"
  • "images_dataset"
  • "videos_project"
  • "videos_dataset"
  • "volumes_project"
  • "volumes_dataset"
  • "point_cloud_project"
  • "point_cloud_dataset"
  • "point_cloud_episodes_project"
  • "point_cloud_episodes_dataset"

session_tags

List of session tags. Makes app session available in another app session:
e.g serve YOLOV5 running app session is available in Apply NN to Images Project app session
"session_tags": [
"sly_video_tracking",
"sly_smart_annotation"
]
List of available session tags:
  • "sly_video_tracking"
  • "sly_smart_annotation"
  • "deployed_nn"

integrated_into

Integrates app into selected tool.
e.g smart tool app can be used in image annotation tool
"integrated_into": ["image_annotation_tool", "video_annotation_tool"]
List of available options:
  • "panel"
  • "files"
  • "standalone"
  • "image_annotation_tool"
  • "video_annotation_tool"
  • "dicom_annotation_tool"
  • "pointcloud_annotation_tool"

task_location

Defines where the task will be displayed on app launch. If specified as "workspace_tasks", app will be displayed in both workspace tasks and app session pages
Task Location
"task_location": "workspace_tasks"
Available task locations:
  • "workspace_tasks" - suitable for application that directly interacts with data from the workspace (e.g. import/export apps)
  • "application_sessions" - suitable for the application that is tied to the team and can work in multiple workspaces (e.g. server-like apps)

hotkeys

Specifies hotkeys that can be used in app
"hotkeys": [
{"hotkey": "ctrl+m", "command": "inference"}
]

restart_policy

Restarts app when certain condition occurs. restart_policy can be found in modal window advanced settings when launching app
"restart_policy": "on_error"
restart policy location

main_script

Legacy property
Relative path to main script from project root. Can not be used with v2.0.0 apps, use main_script or entrypoint
"main_script": "src/main.py"

gui_template

Legacy property
Relative path to GUI template from project root. Can not be used with v2.0.0 apps.
"gui_template": "src/gui.html"

Configuration examples

Configurations will not vary that much depending on type of the project, whether it's a small headless app or complicated app with UI and a lot of widgets.
Common app config example:
{
"name": "App name here",
"type": "app",
"version": "2.0.0",
"categories": ["development"],
"description": "App description here",
"entrypoint": "python -m uvicorn src.main:app --host 0.0.0.0 --port 8000"
"task_location": "workspace_tasks",
"icon": "https://icon.png",
"poster": "https://poster.png"
}
We'll consider a few examples of app configs:
  1. 1.
    Headless
  2. 2.
  3. 3.