Jupyter Notebook plugin for `Tutor <https://docs.tutor.edly.io>`__
======================================================================
This is a plugin for Tutor that makes it easy to integrate `Jupyter <https://jupyter.org/>`__ notebooks in `Open edX <https://openedx.org>`__. It achieves the following:
1. Install the official `jupyter-xblock <https://github.com/overhangio/jupyter-xblock/>`__ in the Open edX LMS and Studio.
2. Run a Docker-based `JupyterHub <https://jupyterhub.readthedocs.io/en/stable/>`__ instance with a `Docker spawner <https://jupyterhub-dockerspawner.readthedocs.io/en/latest/>`__.
In pratice, it means that students will be allocated Docker containers with limited CPU and memory to run their custom notebooks.
⚠️ Compatibility with Kubernetes was not battle-tested. Please report any issue you face. For a more production-ready Kubernetes environment, you are encouraged to check the documentation of the `Zero to JupyterHub with Kubernetes <https://z2jh.jupyter.org/en/stable/resources/reference.html>`__ project.
Installation
------------
::
tutor plugins install jupyter
Usage
-----
Enable the plugin::
tutor plugins enable jupyter
Re-build the "openedx" Docker image to install the Jupyter XBlock::
tutor images build openedx
Launch your platform again::
tutor local launch
Print the default passport ID::
echo "$(tutor config printvalue JUPYTER_DEFAULT_PASSPORT_ID):$(tutor config printvalue JUPYTER_LTI_CLIENT_KEY):$(tutor config printvalue JUPYTER_LTI_CLIENT_SECRET)"
Make a note of the printed value. Go to the Studio Tools ➡️ Advanced Settings ➡️ LTI Passports. Insert the passport value:
.. image:: https://raw.githubusercontent.com/overhangio/jupyter-xblock/main/static/screenshots/studio-advanced-settings-lti.png
:alt: Studio advanced settings
In "Advanced Module List" add "jupyter" (with quotes):
.. image:: https://raw.githubusercontent.com/overhangio/jupyter-xblock/main/static/screenshots/studio-advanced-settings.png
:alt: Studio advanced settings
You should then be able to create an advanced Jupyter XBlock in the Studio:
> Add New Component ➡️ Advanced ➡️ Jupyter notebook
The default `"hello" <https://github.com/overhangio/jupyter-xblock/blob/main/static/notebooks/hello.ipynb>`__ notebook will be pulled from the jupyter-block repository and displayed in the studio.
Configuration
-------------
Settings
~~~~~~~~
This plugin has the following Tutor settings. Each setting can be printed with ``tutor config printvalue JUPYTER_SETTING_NAME`` and modified with ``tutor config save --set JUPYTER_SETTING_NAME=value``.
Default settings:
- JUPYTER_DOCKER_IMAGE_HUB (default: ``"{{ DOCKER_REGISTRY }}overhangio/jupyterhub:{{ JUPYTER_VERSION }}"``)
- JUPYTER_DOCKER_IMAGE_LAB (default: ``"{{ DOCKER_REGISTRY }}overhangio/jupyterlab:{{ JUPYTER_VERSION }}"``)
- JUPYTER_HOST (default: ``"jupyter.{{ LMS_HOST }}"``)
- JUPYTER_DEFAULT_PASSPORT_ID (default: ``"jupyterhub"``)
- JUPYTER_LTI_CLIENT_KEY (default: ``"openedx"``)
- JUPYTER_HUB_MYSQL_DATABASE (default: ``"jupyterhub"``)
- JUPYTER_HUB_MYSQL_USERNAME (default: ``"jupyterhub"``)
- JUPYTER_LAB_CPU_LIMIT (default: ``None``)
- JUPYTER_LAB_MEMORY_LIMIT (default: ``"200M"``)
Unique, user-specific settings:
- JUPYTER_HUB_COOKIE_SECRET (default: ``"{{ 32|jupyterhub_crypt_key }}"``)
- JUPYTER_HUB_CRYPT_KEY (default: ``"{{ 32|jupyterhub_crypt_key }}"``)
- JUPYTER_HUB_MYSQL_PASSWORD (default: ``"{{ 24|random_string }}"``)
- JUPYTER_LTI_CLIENT_SECRET (default: ``"{{ 24|random_string }}"``)
JupyterHub
~~~~~~~~~~
The configuration template for the JupyterHub instance is stored in `jupyterhub_config.py <./tutorjupyter/templates/jupyter/apps/jupyterhub_config.py>`__. This template file includes a ``{{ patch("jupyterhub-config") }}`` statement, which means that its contents can be overridden by creating an ad-hoc Tutor plugin. For instance, to add custom LTI keys to your JupyterHub instance::
from tutor import hooks
hooks.Filters.ENV_PATCHES.add_item(
(
"jupyterhub-config",
"""
# Add LTI keys to the authenticator
c.LTI11Authenticator.consumers["my-lti-key"] = "my-lti-secret"
"""
)
)
Lab environment
~~~~~~~~~~~~~~~
By default, Jupyter lab notebooks will be spawned that do not include extra Python packages or dependencies. To modify the "jupyterlab" Docker image and add extra Python packages (for example), you should create a Tutor plugin that implements the "jupyter-lab-dockerfile" patch::
from tutor import hooks
hooks.Filters.ENV_PATCHES.add_item(
(
"jupyter-lab-dockerfile",
"""
# Install extra Python packages
RUN pip install matplotlib scipy seaborn
"""
)
)
Then build the lab image again::
tutor config save
tutor images build jupyterlab
You should now be able to run ``import matplotlib`` statements within your Jupyter notebooks.
Troubleshooting
---------------
This Tutor plugin is maintained by Abdul-Muqadim from `Edly <https://edly.io>`__. Community support is available from the official `Open edX forum <https://discuss.openedx.org>`__. Do you need help with this plugin? See the `troubleshooting <https://docs.tutor.edly.io/troubleshooting.html>`__ section from the Tutor documentation.
License
-------
This work is licensed under the terms of the `GNU Affero General Public License (AGPL) <https://github.com/overhangio/tutor-jupyter/blob/release/LICENSE.txt>`_.
Raw data
{
"_id": null,
"home_page": "https://github.com/overhangio/tutor-jupyter",
"name": "tutor-jupyter",
"maintainer": "Edly",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "abdul.muqadim@arbisoft.com",
"keywords": null,
"author": "Edly",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/e7/f7/5086e5fea408eea2ef428a2e34c9a23faf2455a7b5569335478d7ed19447/tutor_jupyter-18.1.1.tar.gz",
"platform": null,
"description": "Jupyter Notebook plugin for `Tutor <https://docs.tutor.edly.io>`__\n======================================================================\n\nThis is a plugin for Tutor that makes it easy to integrate `Jupyter <https://jupyter.org/>`__ notebooks in `Open edX <https://openedx.org>`__. It achieves the following:\n\n1. Install the official `jupyter-xblock <https://github.com/overhangio/jupyter-xblock/>`__ in the Open edX LMS and Studio.\n2. Run a Docker-based `JupyterHub <https://jupyterhub.readthedocs.io/en/stable/>`__ instance with a `Docker spawner <https://jupyterhub-dockerspawner.readthedocs.io/en/latest/>`__.\n\nIn pratice, it means that students will be allocated Docker containers with limited CPU and memory to run their custom notebooks.\n\n\u26a0\ufe0f Compatibility with Kubernetes was not battle-tested. Please report any issue you face. For a more production-ready Kubernetes environment, you are encouraged to check the documentation of the `Zero to JupyterHub with Kubernetes <https://z2jh.jupyter.org/en/stable/resources/reference.html>`__ project.\n\nInstallation\n------------\n\n::\n\n tutor plugins install jupyter\n\nUsage\n-----\n\nEnable the plugin::\n\n tutor plugins enable jupyter\n\nRe-build the \"openedx\" Docker image to install the Jupyter XBlock::\n\n tutor images build openedx\n\nLaunch your platform again::\n\n tutor local launch\n\nPrint the default passport ID::\n\n echo \"$(tutor config printvalue JUPYTER_DEFAULT_PASSPORT_ID):$(tutor config printvalue JUPYTER_LTI_CLIENT_KEY):$(tutor config printvalue JUPYTER_LTI_CLIENT_SECRET)\"\n\nMake a note of the printed value. Go to the Studio Tools \u27a1\ufe0f Advanced Settings \u27a1\ufe0f LTI Passports. Insert the passport value:\n\n.. image:: https://raw.githubusercontent.com/overhangio/jupyter-xblock/main/static/screenshots/studio-advanced-settings-lti.png\n :alt: Studio advanced settings\n\n\nIn \"Advanced Module List\" add \"jupyter\" (with quotes):\n\n.. image:: https://raw.githubusercontent.com/overhangio/jupyter-xblock/main/static/screenshots/studio-advanced-settings.png\n :alt: Studio advanced settings\n\nYou should then be able to create an advanced Jupyter XBlock in the Studio:\n\n> Add New Component \u27a1\ufe0f Advanced \u27a1\ufe0f Jupyter notebook\n\nThe default `\"hello\" <https://github.com/overhangio/jupyter-xblock/blob/main/static/notebooks/hello.ipynb>`__ notebook will be pulled from the jupyter-block repository and displayed in the studio.\n\n\nConfiguration\n-------------\n\nSettings\n~~~~~~~~\n\nThis plugin has the following Tutor settings. Each setting can be printed with ``tutor config printvalue JUPYTER_SETTING_NAME`` and modified with ``tutor config save --set JUPYTER_SETTING_NAME=value``.\n\nDefault settings:\n\n- JUPYTER_DOCKER_IMAGE_HUB (default: ``\"{{ DOCKER_REGISTRY }}overhangio/jupyterhub:{{ JUPYTER_VERSION }}\"``)\n- JUPYTER_DOCKER_IMAGE_LAB (default: ``\"{{ DOCKER_REGISTRY }}overhangio/jupyterlab:{{ JUPYTER_VERSION }}\"``)\n- JUPYTER_HOST (default: ``\"jupyter.{{ LMS_HOST }}\"``)\n- JUPYTER_DEFAULT_PASSPORT_ID (default: ``\"jupyterhub\"``)\n- JUPYTER_LTI_CLIENT_KEY (default: ``\"openedx\"``)\n- JUPYTER_HUB_MYSQL_DATABASE (default: ``\"jupyterhub\"``)\n- JUPYTER_HUB_MYSQL_USERNAME (default: ``\"jupyterhub\"``)\n- JUPYTER_LAB_CPU_LIMIT (default: ``None``)\n- JUPYTER_LAB_MEMORY_LIMIT (default: ``\"200M\"``)\n\nUnique, user-specific settings:\n\n- JUPYTER_HUB_COOKIE_SECRET (default: ``\"{{ 32|jupyterhub_crypt_key }}\"``)\n- JUPYTER_HUB_CRYPT_KEY (default: ``\"{{ 32|jupyterhub_crypt_key }}\"``)\n- JUPYTER_HUB_MYSQL_PASSWORD (default: ``\"{{ 24|random_string }}\"``)\n- JUPYTER_LTI_CLIENT_SECRET (default: ``\"{{ 24|random_string }}\"``)\n\nJupyterHub\n~~~~~~~~~~\n\nThe configuration template for the JupyterHub instance is stored in `jupyterhub_config.py <./tutorjupyter/templates/jupyter/apps/jupyterhub_config.py>`__. This template file includes a ``{{ patch(\"jupyterhub-config\") }}`` statement, which means that its contents can be overridden by creating an ad-hoc Tutor plugin. For instance, to add custom LTI keys to your JupyterHub instance::\n\n from tutor import hooks\n\n hooks.Filters.ENV_PATCHES.add_item(\n (\n \"jupyterhub-config\",\n \"\"\"\n # Add LTI keys to the authenticator\n c.LTI11Authenticator.consumers[\"my-lti-key\"] = \"my-lti-secret\"\n \"\"\"\n )\n )\n\nLab environment\n~~~~~~~~~~~~~~~\n\nBy default, Jupyter lab notebooks will be spawned that do not include extra Python packages or dependencies. To modify the \"jupyterlab\" Docker image and add extra Python packages (for example), you should create a Tutor plugin that implements the \"jupyter-lab-dockerfile\" patch::\n\n from tutor import hooks\n\n hooks.Filters.ENV_PATCHES.add_item(\n (\n \"jupyter-lab-dockerfile\",\n \"\"\"\n # Install extra Python packages\n RUN pip install matplotlib scipy seaborn\n \"\"\"\n )\n )\n\nThen build the lab image again::\n\n tutor config save\n tutor images build jupyterlab\n\nYou should now be able to run ``import matplotlib`` statements within your Jupyter notebooks.\n\nTroubleshooting\n---------------\n\nThis Tutor plugin is maintained by Abdul-Muqadim from `Edly <https://edly.io>`__. Community support is available from the official `Open edX forum <https://discuss.openedx.org>`__. Do you need help with this plugin? See the `troubleshooting <https://docs.tutor.edly.io/troubleshooting.html>`__ section from the Tutor documentation.\n\nLicense\n-------\n\nThis work is licensed under the terms of the `GNU Affero General Public License (AGPL) <https://github.com/overhangio/tutor-jupyter/blob/release/LICENSE.txt>`_.\n",
"bugtrack_url": null,
"license": "AGPLv3",
"summary": "Jupyter Notebook plugin for Tutor",
"version": "18.1.1",
"project_urls": {
"Code": "https://github.com/overhangio/tutor-jupyter",
"Homepage": "https://github.com/overhangio/tutor-jupyter",
"Issue tracker": "https://github.com/overhangio/tutor-jupyter/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e7f75086e5fea408eea2ef428a2e34c9a23faf2455a7b5569335478d7ed19447",
"md5": "60493ebe7ec1af08e4d874eb4d03d11b",
"sha256": "e00a87081433702b086d7b13ba8e2a0d9473d8f1782771d3b3ba3b28fb9f97e8"
},
"downloads": -1,
"filename": "tutor_jupyter-18.1.1.tar.gz",
"has_sig": false,
"md5_digest": "60493ebe7ec1af08e4d874eb4d03d11b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 21927,
"upload_time": "2024-12-16T10:37:43",
"upload_time_iso_8601": "2024-12-16T10:37:43.874869Z",
"url": "https://files.pythonhosted.org/packages/e7/f7/5086e5fea408eea2ef428a2e34c9a23faf2455a7b5569335478d7ed19447/tutor_jupyter-18.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-16 10:37:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "overhangio",
"github_project": "tutor-jupyter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tutor-jupyter"
}
JSON
