Supervisely
About SuperviselyEcosystemContact usSlack
  • 💻Supervisely Developer Portal
  • 🎉Getting Started
    • Installation
    • Basics of authentication
    • Intro to Python SDK
    • Environment variables
    • Supervisely annotation format
      • Project Structure
      • Project Meta: Classes, Tags, Settings
      • Objects
      • Tags
      • Image Annotation
      • Video Annotation
      • Point Clouds Annotation
      • Point Cloud Episode Annotation
      • Volumes Annotation
    • Python SDK tutorials
      • Images
        • Images
        • Image and object tags
        • Spatial labels on images
        • Keypoints (skeletons)
        • Multispectral images
        • Multiview images
        • Advanced: Optimized Import
        • Advanced: Export
      • Videos
        • Videos
        • Video and object tags
        • Spatial labels on videos
      • Point Clouds
        • Point Clouds (LiDAR)
        • Point Cloud Episodes and object tags
        • 3D point cloud object segmentation based on sensor fusion and 2D mask guidance
        • 3D segmentation masks projection on 2D photo context image
      • Volumes
        • Volumes (DICOM)
        • Spatial labels on volumes
      • Common
        • Iterate over a project
        • Iterate over a local project
        • Progress Bar tqdm
        • Cloning projects for development
    • Command Line Interface (CLI)
      • Enterprise CLI Tool
        • Instance administration
        • Workflow automation
      • Supervisely SDK CLI
    • Connect your computer
      • Linux
      • Windows WSL
      • Troubleshooting
  • 🔥App development
    • Basics
      • Create app from any py-script
      • Configuration file
        • config.json
        • Example 1. Headless
        • Example 2. App with GUI
        • v1 - Legacy
          • Example 1. v1 Modal Window
          • Example 2. v1 app with GUI
      • Add private app
      • Add public app
      • App Compatibility
    • Apps with GUI
      • Hello World!
      • App in the Image Labeling Tool
      • App in the Video Labeling Tool
      • In-browser app in the Labeling Tool
    • Custom import app
      • Overview
      • From template - simple
      • From scratch - simple
      • From scratch GUI - advanced
      • Finding directories with specific markers
    • Custom export app
      • Overview
      • From template - simple
      • From scratch - advanced
    • Neural Network integration
      • Overview
      • Serving App
        • Introduction
        • Instance segmentation
        • Object detection
        • Semantic segmentation
        • Pose estimation
        • Point tracking
        • Object tracking
        • Mask tracking
        • Image matting
        • How to customize model inference
        • Example: Custom model inference with probability maps
      • Serving App with GUI
        • Introduction
        • How to use default GUI template
        • Default GUI template customization
        • How to create custom user interface
      • Inference API
      • Training App
        • Overview
        • Tensorboard template
        • Object detection
      • High level scheme
      • Custom inference pipeline
      • Train and predict automation model pipeline
    • Advanced
      • Advanced debugging
      • How to make your own widget
      • Tutorial - App Engine v1
        • Chapter 1 Headless
          • Part 1 — Hello world! [From your Python script to Supervisely APP]
          • Part 2 — Errors handling [Catching all bugs]
          • Part 3 — Site Packages [Customize your app]
          • Part 4 — SDK Preview [Lemons counter app]
          • Part 5 — Integrate custom tracker into Videos Annotator tool [OpenCV Tracker]
        • Chapter 2 Modal Window
          • Part 1 — Modal window [What is it?]
          • Part 2 — States and Widgets [Customize modal window]
        • Chapter 3 UI
          • Part 1 — While True Script [It's all what you need]
          • Part 2 — UI Rendering [Simplest UI Application]
          • Part 3 — APP Handlers [Handle Events and Errors]
          • Part 4 — State and Data [Mutable Fields]
          • Part 5 — Styling your app [Customizing the UI]
        • Chapter 4 Additionals
          • Part 1 — Remote Developing with PyCharm [Docker SSH Server]
      • Custom Configuration
        • Fixing SSL Certificate Errors in Supervisely
        • Fixing 400 HTTP errors when using HTTP instead of HTTPS
      • Autostart
      • Coordinate System
      • MLOps Workflow integration
    • Widgets
      • Input
        • Input
        • InputNumber
        • InputTag
        • BindedInputNumber
        • DatePicker
        • DateTimePicker
        • ColorPicker
        • TimePicker
        • ClassesMapping
        • ClassesColorMapping
      • Controls
        • Button
        • Checkbox
        • RadioGroup
        • Switch
        • Slider
        • TrainValSplits
        • FileStorageUpload
        • Timeline
        • Pagination
      • Text Elements
        • Text
        • TextArea
        • Editor
        • Copy to Clipboard
        • Markdown
        • Tooltip
        • ElementTag
        • ElementTagsList
      • Media
        • Image
        • LabeledImage
        • GridGallery
        • Video
        • VideoPlayer
        • ImagePairSequence
        • Icons
        • ObjectClassView
        • ObjectClassesList
        • ImageSlider
        • Carousel
        • TagMetaView
        • TagMetasList
        • ImageAnnotationPreview
        • ClassesMappingPreview
        • ClassesListPreview
        • TagsListPreview
        • MembersListPreview
      • Selection
        • Select
        • SelectTeam
        • SelectWorkspace
        • SelectProject
        • SelectDataset
        • SelectItem
        • SelectTagMeta
        • SelectAppSession
        • SelectString
        • Transfer
        • DestinationProject
        • TeamFilesSelector
        • FileViewer
        • Dropdown
        • Cascader
        • ClassesListSelector
        • TagsListSelector
        • MembersListSelector
        • TreeSelect
        • SelectCudaDevice
      • Thumbnails
        • ProjectThumbnail
        • DatasetThumbnail
        • VideoThumbnail
        • FolderThumbnail
        • FileThumbnail
      • Status Elements
        • Progress
        • NotificationBox
        • DoneLabel
        • DialogMessage
        • TaskLogs
        • Badge
        • ModelInfo
        • Rate
        • CircleProgress
      • Layouts and Containers
        • Card
        • Container
        • Empty
        • Field
        • Flexbox
        • Grid
        • Menu
        • OneOf
        • Sidebar
        • Stepper
        • RadioTabs
        • Tabs
        • TabsDynamic
        • ReloadableArea
        • Collapse
        • Dialog
        • IFrame
      • Tables
        • Table
        • ClassicTable
        • RadioTable
        • ClassesTable
        • RandomSplitsTable
        • FastTable
      • Charts and Plots
        • LineChart
        • GridChart
        • HeatmapChart
        • ApexChart
        • ConfusionMatrix
        • LinePlot
        • GridPlot
        • ScatterChart
        • TreemapChart
        • PieChart
      • Compare Data
        • MatchDatasets
        • MatchTagMetas
        • MatchObjClasses
        • ClassBalance
        • CompareAnnotations
      • Widgets demos on github
  • 😎Advanced user guide
    • Objects binding
    • Automate with Python SDK & API
      • Start and stop app
      • User management
      • Labeling Jobs
  • 🖥️UI widgets
    • Element UI library
    • Supervisely UI widgets
    • Apexcharts - modern & interactive charts
    • Plotly graphing library
  • 📚API References
    • REST API Reference
    • Python SDK Reference
Powered by GitBook
On this page
  • Introduction
  • Version releases and Branch releases
  • Multi-app repositories
  • How to share the private app with Team members
  • Option 1. [👍 Recommended] CLI - Run command in terminal.
  • Step 0. Install Supervisely SDK
  • Create a .env file ~/supervisely.env with the following content (learn more here:
  • Development in a team
  • How to get APP_RELEASE_TOKEN
  • How to pass ownership of an app to another user
  • Step 1. Prepare a directory with app sources.
  • Step 2. Release
  • Option 2. Connect your git account (Github or Gitlab).
  • Step 1. Generate new personal token
  • Step 2. Create repository
  • Step 3. Make it a Supervisely App repository
  • Step 4. Add Application to Supervisely
  • Step 5. Check your first application
  • Option 3. Create a release on GitHub
  • Step 1. Create a repository
  • Step 2. Add GitHub workflow
  • Step 3. Create a release

Was this helpful?

Edit on GitHub
  1. App development
  2. Basics

Add private app

Introduction

Supervisely supports both private and public apps.

🔒 Private apps are those that are available only on your private Supervisely Instance (Enterprise Edition) in your account.

🌎 Public apps are available on all private Supervisely Instances and in Community Edition. The guidelines for adding public apps will be covered in other tutorials.

This tutorial covers the case of adding a custom private app to your private instance. It means that this app will be available only for your account and only on your private Supervisely instance.

Apps, developed by the Supervisely team, are open-sourced and are available on all Supervisely instances (Community Edition and all private customer's instances with Enterprise Edition license). The case of publishing an app to the global public Supervisely Ecosystem will be covered in another tutorial.

Version releases and Branch releases

There are two types of releases: version and branch. The version release is made from the main or master branch. With each version release, a release tag is added to the last commit. This tag is used to identify the release version and is important for the app versioning. If during the release process, the tag is not created, the release will be rejected. With version releases, you can specify the release version and description. The branch releases are for testing and debugging and are made from any other branch except main or master. With branch releases, you can't specify the release version and description. The release version will be the branch name.

Multi-app repositories

In Supervisely you can have a single git repository with multiple applications. It is advised to have connected applications with a common codebase in the same repository. By default supervisely release command will release the application from the root directory of the repository. If you have multiple applications in the repository, you can specify the path to the application directory with the -a flag. The application directory is a directory with a config.json file. Such applications are called subapps. For example, if you have a repository with two applications in the train and serve directories, you can release the train application with the following command:

supervisely release -a train

When making a release the tag is added to the last commit. And since all of the applications are in the same repository, it is impossible to differentiate the release tags of different applications. Therefore, it is advised to do a release for each subapp with every new version.

How to share the private app with Team members

After the private app is released it will be available for the user who released the app. The app can be shared with the team members without the need to share it with the whole instance. To do it, you need to run the app once while being a member of the team. After that, the app will appear on the App sessions page and will become available by URL for any team member.

Option 1. [👍 Recommended] CLI - Run command in terminal.

Step 0. Install Supervisely SDK

Run command in terminal to install Supervisely SDK

pip install supervisely
SERVER_ADDRESS="<server-address>"
API_TOKEN="4r47N...xaTatb"

Development in a team

For team development, you need to add APP_RELEASE_TOKEN variable to your ~/supervisely.env file. This token will be used to authenticate your app during the release process. If APP_RELEASE_TOKEN is present in your ~/supervisely.env file, then the app will be owned by the user associated with the token and any user will be able to do a release if he has the token. Otherwise, the app will be owned by the user who released the app and releases from other users will be rejected.

How to get APP_RELEASE_TOKEN

  1. Create a new user on your instance. This user will be used for releasing apps. You can name it dev or dev-team or whatever you want.

  1. Login as this user and copy API token.

  1. Use this token as APP_RELEASE_TOKEN in your ~/supervisely.env file.

SERVER_ADDRESS="<server-address>"
API_TOKEN="4r47N...xaTatb"
APP_RELEASE_TOKEN="xaTatb...4r47N"

How to pass ownership of an app to another user

If you released an app without APP_RELEASE_TOKEN and now want to continue development in a team you can pass the ownership to the user created in previous steps. To do this you need to go to the private app page, navigate to the bottom left part and click Change owner button. Then input login of the user. You will be still able to see this app in your private apps. But to make new releases you will need to use APP_RELEASE_TOKEN of the new owner.

Step 1. Prepare a directory with app sources.

You are a developer and you implemented an app. App sources are on your local computer in some directory. Go to this folder. For example, the folder structure will look like this:

.
├── README.md
├── config.json
├── requirements.txt
└── src
    └── main.py

Step 2. Release

Execute the following command in the terminal to release an app. By default, this command will pack and release files in the current folder.

supervisely release

You will be asked for a release description and in case of releasing from main/master branch for release version. After that, you will see a summary message and confirmation request. If releasing from main/master branch new tag will be created and pushed to remote (You may be asked for git authentication). Then if there are no errors you will see the "App release successfully!" message.

You can provide release version and release description by providing --release-version and --release-description options to the CLI

Your app will appear in the section 🔒 private apps` in Ecosystem.

Thus you can quickly do releases of your app. All releases will be available on the application page. Just select the release in the modal window in the advanced section before running the app. The latest release is selected by default.

You can store several applications in one repository. To release an application from such repository, go to root folder of the repository, then run supervisely release with -a flag and specify the relative path to folder with application configuration file

cd ~/code/yolov5
supervisely release -a apps/train

Option 2. Connect your git account (Github or Gitlab).

Since Supervisely app is just a git repository, we support public and private repos from the most popular hosting platforms in the world - GitHub and GitLab. You just need to generate and provide the access token to your repo.

Step 1. Generate new personal token

GitHub

To access private GitHub repositories, you will need to generate a personal token. Please note, that this token will provide your Supervisely instance a read access to all repositories, available for this GitHub account — you may want to create a dedicated GutHub account for a single Supervisely App repository.

Select "repo" access scope and click "Generate token" button. Save generated token — you will need it later.

GitLab

To access private GitLab repositories, you will need to generate a personal token. Please note, that this token will provide your Supervisely instance a read access to all repositories, available for this GitLab account — you may want to create a dedicated GutLab account for a single Supervisely App repository.

Select with "read_api", "read_repository" scopes enabled and click "Create personal access token" button. Save generated token — you will need it later.

Step 2. Create repository

GitHub

GitLab

Let's create a new GitLab repository that we will use to deploy a new Supervisely application. Create a new project.

You can create a public repository alright — you will still need a personal token and further steps are gonna be the same.

Step 3. Make it a Supervisely App repository

We will download its source code, extract it, create a new repository and initialize it:

wget -O while-true-app.zip  https://github.com/supervisely-ecosystem/while-true-script/archive/refs/heads/master.zip
unzip while-true-app.zip
cd while-true-script-master/
git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/supervisely/my-first-private-app.git # Your actual repository name here...
git push -u origin main

You will find a few files in your new application:

  • config.json describes your app name, type, etc.

  • requirements.txt list python packages you will need

  • README.md in markdown format

  • src/main.py your entry-point python file

Let's leave it as is for now

Step 4. Add Application to Supervisely

Go to Ecosystem page → Private apps → Click "Add private app"

Step 5. Check your first application

Now, open the Ecosystem page in the left menu and choose "Private Apps" in the right menu. You should see here your new application after a minute. Add it to your team and try it out!

Next time you push a new update to your repository, do not forget to open the application in Ecosystem and click "Refresh" button to update it.

Option 3. Create a release on GitHub

Only for Supervisely Team.

Step 1. Create a repository

Step 2. Add GitHub workflow

name: Release
run-name: Release version "${{ github.event.release.tag_name }}"
on:
  release:
    types: [published]
    branches:
      - main
      - master
jobs:
  Supervisely-Release:
    ***
    with:
      ***
      SUBAPP_PATHS: "__ROOT_APP__, subapp" <-- Change this variable

In each of these files, you should change the following variable: SUBAPP_PATHS - Paths to directories with applications within the repository (directory where the config.json file is located). If the application is located in a root directory, then you should specify __ROOT_APP__ instead of the path. Paths should be separated by commas.

In the example above, releases are configured for two applications in the repository: the one which is located in root directory and the one which is located in the subapp directory. Example for the repository with two applications, located in train and serve directories: SUBAPP_PATHS: "train, serve".

Step 3. Create a release

3.1 Version release

The workflow we created in the previous step will be triggered when you publish a release in the repository.

To create a release, go to the repository page on GitHub and click on the Releases tab. Then click on the Create a new release or Draft a new release button. Choose a tag version in semver format (v1.0.0) and a release title. Then click on the Publish release button.

Do not change the Target of the release. It should always be main or master.

3.2 Branch release

The workflow we created in the previous step will be triggered when you push a branch (except "main" or "master") in the repository.

You can disable branch release by adding the branch name to branches-ignore list in the .github/workflows/release_branch.yml workflow file. See below

name: Release branch
run-name: Release "${{ github.ref_name }}" branch
on:
  push:
    branches-ignore:
      - main
      - master
      - branch-to-ignore <-- Add branch name here
jobs:
  Supervisely-Release:

After the release is published the workflow will be triggered and you can see the release progress in the Actions tab. If the workflow is successful, the app will appear in the ecosystem.

PreviousExample 2. v1 app with GUINextAdd public app

Last updated 1 year ago

Was this helpful?

Create a .env file ~/supervisely.env with the following content (learn more :

dev-in-team-1
dev-in-team-2
dev-in-team-3
dev-in-team-4
dev-in-team-change-ownership
release from main/master branch
release from other branch
private apps
app versions

Open GitHub → Settings → Developer settings → and click Generate new token.

Open GilLab → Settings →

Let's create a new GitHub repository that we will use to deploy a new Supervisely application. Create a : do not forget to choose "Private" visibility option.

In this tutorial we will use code-base as a starting point — it's a bare minimum sample application that, basically, just runs an infinite loop.

Create an app repository on GitHub in a . *

Add a GitHub workflow files from :

For version releases (see step 3.1):

For branch releases (see step 3.2):

🔥
here
Personal access tokens
Access Tokens
new private GitHub repository
While(true) app
Supervisely-ecosystem organization
How to create an app
this repository
.github/workflows/release.yml
.github/workflows/release_branch.yml