JupyterHub

JupyterHub gives you a personal JupyterLab session running on the cluster, e.g. https://processing.ops.rs-python.eu/jupyter on the reference platform. Log in with your Keycloak account (you need to be a member of the JupyterHub users group, see User rights).

JupyterLab combines in a single web interface notebooks, a text editor, a terminal and a file browser, with flexible layouts and support for many file formats. See the JupyterLab user guide.

What is already set up for you

• The latest rs-client-libraries and their dependencies (Prefect, Dask Gateway, pystac-client...) are installed. Check the version with pip show rs-client-libraries from a terminal.

• The environment variables needed to call the services are set, e.g.:

  Variable	Description
  RSPY_WEBSITE	URL of the RS-Python web services.
  RSPY_UAC_HOMEPAGE, RSPY_UAC_CHECK_URL	URLs of the API Key Manager.
  PREFECT_API_URL	URL of the Prefect server of your group.
  PREFECT_WORK_POOL_INTEGRATED, PREFECT_WORK_POOL_SANDBOX, PREFECT_WORK_POOL_MONITORING	Names of the Prefect work pools, see Prefect.
  DASK_GATEWAY_ADDRESS, DASK_GATEWAY_PUBLIC	Internal and public addresses of the Dask Gateway.
  S3_ENDPOINT, S3_REGION	Object storage endpoint.
  TEMPO_ENDPOINT	OpenTelemetry endpoint for the traces.

• The variables that you write in the ~/.env file of your home directory are loaded automatically when a notebook kernel starts. This is where your API key is saved as RSPY_APIKEY (see Set up your environment).

• Additional Jupyter kernels, one per Python and Dask version used by the Dask clusters, are available: a Dask client must use the same Python and Dask versions as the cluster it connects to (see Dask images).

Your home directory, /home/rspy, is persistent: your files are kept when your session is stopped.

Demo notebooks

The rs-demo repository contains notebooks that show how to use the services, the libraries and the flows. Clone it in your home directory, from a JupyterHub terminal:

git clone https://github.com/RS-PYTHON/rs-demo.git

Most of the demos start by calling init_demo() from rs-demo/notebooks/resources/utils.py, that initialises your Prefect block, an RsClient instance and your object storage credentials.

Use another rs-client-libraries version

To test a version of the rs-client-libraries that is not yet installed in the JupyterHub image (e.g. a development branch), either:

• install its wheel package for your user only. Download it from the Artifacts section of the publish workflow run of your branch, or build it with poetry build --format wheel, upload it to your session, then from a terminal:

  pip install --user rs_client_libraries-<version>-py3-none-any.whl
  opentelemetry-bootstrap -a install
  

• or clone the repository and add it to the Python path of your notebook:

  import sys
  sys.path.insert(0, "/home/rspy/rs-client-libraries")  # path of your clone
  import rs_client
  print(rs_client.__path__)
  

To update the version installed for everyone, ask your administrator to deploy a new JupyterHub image (built by the rs-workflow-env CI/CD).