CryoInTheCloud JupyterHub user image

The JupyterHub docker image used for hub.cryointhecloud.com,
hosted on https://quay.io/repository/cryointhecloud/cryo-hub-image

The image is built with repo2docker, which uses
Ubuntu Bionic Beaver (18.04) as the base image. If you'd like to run a test build
locally, please read the repo2docker Getting Started
doc and the
repo2docker Configuration Files
doc.

Updating packages in this repository

You can add or update packages on the cryointhecloud hub by making pull requests to this
repository. Follow these steps:

1. Edit either the environment.yml
   file (for most packages) or apt.txt
   file (for packages that need to be used in the Linux Desktop environment in the cloud).
2. Start a pull request -
   you can even do that just from the GitHub UI! A bot will comment with a link to
   mybinder.org where you can test your pull request to make sure it works
   as you would expect.
3. In the Pull Request, write a comment with the slash command /condalock.
   This will refresh the conda-lock.yml
   file that contains a snapshot of the exact library versions contained in the
   conda environment, which will be useful for reproducibility.
4. If the bot does not commit any changes to update the conda-lock.yml file in your PR, you can check the
   status of the action in the "Actions" tab; the bot could fail silently, in which case you should address
   any errors and re-comment with the /condalock command.

Testing locally

To test the build locally, first ensure you have an up-to-date conda lock file, then
build with repo2docker (if your conda lock file was already updated by the bot as
described above, you can skip the first line):

conda-lock lock --mamba --kind explicit --file environment.yml --platform linux-64
repo2docker --appendix "$(cat appendix)" .

This build may take up to 30 minutes.

Once the image is built, repo2docker will automatically run a JupyterLab
server and display a message like this:

    To access the notebook, open this file in a browser:
        file:///home/<YOUR_USERNAME>/.local/share/jupyter/runtime/nbserver-27-open.html
    Or copy and paste this URL:
        http://127.0.0.1:53695/?token=<YOUR_TOKEN>

Click the URL on the last line of the repo2docker output to open the local JupyterLab
instance in your browser, and you're ready to test!

From here, you'll be able to locally test anything you can do in a cloud deployment:
run terminal commands, edit and run notebooks, or start a desktop VNC session.

Updating the CryoCloud JupyterHub to use a new image

After your PR gets merged, our GitHub Actions will build and push a new image to
our image repository on quay.io. You
can monitor the progress of this in the GitHub Actions tab in this repo.

Once a new tag appears, someone with JupyterHub Admin permissions on the CryoCloud hub will have to
update the system to use the new image. With the new Other image selector, an admin will need to test
the image on CryoCloud and then ask a 2i2c engineer to update the image by sending them the tag name.

1. When starting CryoCloud, instead of using Python, select Other from the Image selector.
2. Add the tag of the image you want under Custom to use the new tag pushed for the PR in the
   quay.io tags page. Make sure there are
   no trailing spaces!
3. Hit 'Start'. Note that due to a bug in your image, CryoCloud may not start up and will show error messages. The image will need to be fixed if this occurs.
4. Make sure all of the new tools are present and test that your imports work properly in a notebook.
5. The admin can then send an email to 2i2c with the tag we want added to CryoCloud.