Skip to content

How LabConstrictor works

From a notebook that works on your computer to an app that colleagues can install, in five steps. Open one at a time; each links to the guides that show how.

1 Build your notebook(s)

Start with a notebook that already works for you. It is what your colleagues open in the installed app, so there is no separate interface to write.

What to do

  1. Make sure each notebook runs from top to bottom in JupyterLab, and ideally in Google Colab too: keep Colab-only setup inside a check for Colab, and use ipywidgets rather than Colab forms. Write notebooks that run in both Colab and JupyterLab
  2. Paste the version cell at the top of each notebook, fill in current_version and notebook_name (the file name without .ipynb), and raise the version whenever the notebook's logic changes. The app's Welcome notebook uses it to offer updates. Add the version cell
  3. Put what users must read in Markdown cells: code cells are hidden by default in the installed app, and users can show them with Show/Hide Code. Hide code cells

Next: Create and initialise your repository

2 Create and initialise your repository

Your app lives in a GitHub repository made from the LabConstrictor template. A web form gives it its name and version.

What to do

  1. Create your repository from the LabConstrictor template on GitHub (you need a GitHub account). It can be public or private: only people with access to a private repository can download its installers, and only a public one can be listed in the App Centre. Create your repository
  2. Set up template updates once, before you initialise the repository, so that future improvements of the template can reach it. Set up template updates
  3. Create a personal access token for the web form (classic, starting with ghp_). It is not the same token as the one for template updates. Create a personal access token
  4. Fill in the LabConstrictor web form: your project's name, an initial version such as 0.0.1, your repository's URL and the token. The form can also write how the App Centre will describe your app. Initialise your repository
  5. Accept the pull request that the form opens in your repository. Accept a pull request

← Back: Build your notebook(s)Next: Define your requirements

3 Define your requirements

Each notebook needs its own requirements.yaml, which lists the exact package versions it needs, its Python version and a short description.

What to do

  1. Run the Requirements Generator notebook in the environment where your notebook works without errors, on your computer or in Colab. It writes requirements.yaml for you. Generate the requirements of your notebook
  2. If you prefer to write the file by hand, check it with the Requirements Validator notebook.
  3. Keep helper code in your repository's src folder, or use a package installed with pip (list it in requirements.yaml). Upload external code

← Back: Create and initialise your repositoryNext: Add your notebook(s)

4 Add your notebook(s)

Each notebook and its requirements.yaml go into your repository through the LabConstrictor web form, which opens a pull request.

What to do

  1. Upload each notebook with its requirements.yaml in the web form, with your repository's URL and a personal access token (classic) with write access. Several notebooks can go in one pull request. Add or update a notebook
  2. Merge the pull request. A workflow then records each notebook's version and changelog, hides its code and tests that the packages of all your notebooks install together. Check the status of workflows
  3. If that test fails, the merge is undone automatically: download the error log from the failed run's Artifacts, fix the notebook or its requirements and upload again.
  4. To update a notebook later, raise its version and upload it again under exactly the same file name. Update a notebook

← Back: Define your requirementsNext: Create a release and share it

5 Create a release and share it

A release on GitHub builds an installer for each system. You share the release, and anyone who can see your repository can install the app from it.

What to do

  1. Check the Actions tab of your repository: no workflow should be running. Check the status of workflows
  2. Publish a release whose tag is a version number in the form MAJOR.MINOR.PATCH (for example 0.0.1), higher than the last one. It becomes your app's version, and a workflow builds the installers. Create installer files
  3. When the workflow has finished, download the installer for your system from the release's Assets and try it yourself. It comes with a Welcome notebook that lists your notebooks and checks for updates. Install an app
  4. Share the link to your release. The installers are not code-signed yet, so tell people to download only from your release; installing needs an internet connection.
  5. To be found by others, submit your repository to the App Centre. It must be public and have a licence: the template's LICENSE file carries the Cell Migration Lab's copyright line, so put your own name in it. Submit your app

Make it yours (optional)

  1. Your own logo (the installer and desktop icon) and the banner and header images shown in the installer. Add your own logo and installer images
  2. Whether code cells are hidden or shown by default when users open a notebook. Hide code cells
  3. What the App Centre shows on your app's page: screenshots, the development status, what it works with and the paper to cite (labconstrictor-app.yaml). Describe your app for the App Centre
  4. Experimental: tools that the napari, Fiji and QuPath plugins can run, declared in a module named <package>_lc_tools next to your helper code. Only a development version of the installer registers them so far. Declare tools for napari, Fiji and QuPath

When you need more

← Back: Add your notebook(s)

Edit this page on GitHub