Introducing install_guide/the-littlest-jupyterhub and the MATLAB pl…

…ugin for TLJH.

.github/workflows/publish-tljh-matlab.yml

@@ -0,0 +1,65 @@
+# Copyright 2024 The MathWorks, Inc.
+name: Upload Python Package for tljh-matlab
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build-tljh-matlab:
+    # Only run job if release tag contains `tljh-matlab`
+    if: ${{ contains(github.ref, 'tljh-matlab') }}
+
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./install_guides/the-littlest-jupyterhub/tljh-matlab
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: '3.x'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+
+    - name: Build package
+      run: |
+        python -m build
+
+    - name: Upload distributions
+      uses: actions/upload-artifact@v4
+      with:
+          name: release-dists
+          path: install_guides/the-littlest-jupyterhub/tljh-matlab/dist/
+
+  release-tljh-matlab:
+    runs-on: ubuntu-latest
+    needs: 
+      - build-tljh-matlab
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+    environment:
+      name:  pypi
+      url: https://pypi.org/project/tljh-matlab
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: install_guides/the-littlest-jupyterhub/tljh-matlab/dist/
+
+      - name: Publish to PyPI.
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: install_guides/the-littlest-jupyterhub/tljh-matlab/dist

.github/workflows/test-jupyter-matlab-proxy.yml

@@ -12,6 +12,7 @@ on:
       - "src/**"
       - "tests/**"
       - "setup.py"
+
 jobs:
   call-unit-tests:
     # Run unit tests

.github/workflows/test-tljh-matlab.yml

@@ -0,0 +1,50 @@
+# Copyright 2024 The MathWorks, Inc.
+name: Test TLJH-MATLAB package
+
+on:
+  push:
+    branches: [ "main" ]
+    paths:
+      # Only run tests when there are changes to these folders
+      - "./install_guides/the-littlest-jupyterhub/tljh-matlab/**"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v3
+      with:
+        python-version: "3.10"
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install flake8 black
+        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+
+    - name: Install Package
+      run: |
+        cd ./install_guides/the-littlest-jupyterhub/tljh-matlab
+        python -m pip install .
+
+    - name: Lint with flake8
+      run: |
+        cd ./install_guides/the-littlest-jupyterhub/tljh-matlab
+        # stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+
+    - name: Lint with black
+      run: black --check ./install_guides/the-littlest-jupyterhub/tljh-matlab
+
+    # - name: Test with unittest
+    #   run: |
+    #     python -m unittest discover --verbose -s ./install_guides/the-littlest-jupyterhub/tljh-matlab

README.md

@@ -8,14 +8,23 @@ Run MATLAB® code in Jupyter® environments such as Jupyter notebooks, JupyterLa
 
 
 ## Table of Contents
-1. [Features of MATLAB Integration _for Jupyter_](#features-of-matlab-integration-for-jupyter)
-2. [Requirements](#requirements)
-3. [Install](#install)
-4. [Get Started](#get-started)
-    1. [Run MATLAB Code in a Jupyter Notebook](#run-matlab-code-in-a-jupyter-notebook)
-    2. [Open MATLAB in a Browser](#open-matlab-in-a-browser)
-    3. [Edit MATLAB Files in JupyterLab](#edit-matlab-files-in-jupyterlab)
-5. [Limitations](#limitations)
+- [MATLAB Integration _for Jupyter_](#matlab-integration-for-jupyter)
+  - [Table of Contents](#table-of-contents)
+  - [Features of MATLAB Integration _for Jupyter_](#features-of-matlab-integration-for-jupyter)
+  - [Requirements](#requirements)
+  - [Install](#install)
+    - [Install from PyPI](#install-from-pypi)
+    - [Build from Source](#build-from-source)
+    - [Using JupyterHub](#using-jupyterhub)
+    - [Using JupyterHub and The Littlest JupyterHub](#using-jupyterhub-and-the-littlest-jupyterhub)
+    - [Using Simulink](#using-simulink)
+    - [Troubleshooting](#troubleshooting)
+  - [Get Started](#get-started)
+  - [Run MATLAB Code in a Jupyter Notebook](#run-matlab-code-in-a-jupyter-notebook)
+    - [Notes](#notes)
+  - [Open MATLAB in a Browser](#open-matlab-in-a-browser)
+  - [Edit MATLAB Files in JupyterLab](#edit-matlab-files-in-jupyterlab)
+  - [Limitations](#limitations)
 
 
 ## Features of MATLAB Integration _for Jupyter_
@@ -81,9 +90,12 @@ python -m pip install .
 ```
 
 ### Using JupyterHub
+### Using JupyterHub and The Littlest JupyterHub
 
 To use MATLAB with JupyterHub, install the `jupyter-matlab-proxy` Python package in the Jupyter environment launched by your JupyterHub platform. For example, if your JupyterHub platform launches Docker containers, install this package in the Docker image used to launch those containers, using the instructions for [Using MATLAB Integration _for Jupyter_ in a Docker Container](https://github.com/mathworks-ref-arch/matlab-integration-for-jupyter/tree/main/matlab).
 
+To use MATLAB with [The Littlest JupyterHub (TLJH)](https://tljh.jupyter.org/en/stable/index.html#), see [MATLAB Integration for Jupyter on The Littlest JupyterHub](https://github.com/mathworks/jupyter-matlab-proxy/jupyter-matlab-proxy/install_guides/the-littlest-jupyterhub/README.md). You might use this if you want to set up JupyterHub on a single server for a small number of users, such as students in a class.
+
 ### Using Simulink
 
 This package lets you use Simulink® programmatically by entering commands in a Jupyter notebook. To view a model or use other Simulink features that require the Simulink UI, you can use a VNC to connect your Jupyter environment to a Linux desktop where you have MATLAB and Simulink installed. For instructions, see [MATLAB Jupyter VNC Solution](https://github.com/mathworks/jupyter-matlab-vnc-proxy).

SECURITY.md

@@ -3,4 +3,11 @@ Reporting Security Vulnerabilities
 If you believe you have discovered a security vulnerability, please report it to
 [email protected] instead of GitHub. Please see
 [MathWorks Vulnerability Disclosure Policy for Security Researchers](https://www.mathworks.com/company/aboutus/policies_statements/vulnerability-disclosure-policy.html)
-for additional information.
+for additional information.
+
+----
+
+Copyright 2021-2024 The MathWorks, Inc.
+
+----
+

install_guides/the-littlest-jupyterhub/.matlab_env

@@ -0,0 +1,3 @@
+MATLAB_RELEASE=R2024b
+MATLAB_PRODUCT_LIST=MATLAB Symbolic_Math_Toolbox
+MATLAB_INSTALL_DESTINATION=/opt/matlab/testing

install_guides/the-littlest-jupyterhub/README.md

@@ -0,0 +1,53 @@
+# MATLAB Integration for Jupyter on The Littlest JupyterHub
+
+This guide shows how to set up MATLAB and the [MATLAB Integration for Jupyter](https://github.com/mathworks/jupyter-matlab-proxy) on the [The Littlest JupyterHub (TLJH)](https://tljh.jupyter.org/en/stable/index.html#). You might use this if you want to set up JupyterHub on a single server for a small number of users, such as students in a class.
+
+
+## Set up TLJH
+
+The [TLJH Documentation](https://tljh.jupyter.org/en/stable/install/index.html) contains instructions for installing TLJH in different environments. 
+
+Once you have a working TLJH stack, you can add MATLAB into your TLJH stack using the MATLAB Plugin for The Littlest JupyterHub.
+
+## Add MATLAB to TLJH Installation
+This repository contains `tljh-matlab`, the [MATLAB Plugin for The Littlest JupyterHub](https://github.com/mathworks/jupyter-matlab-proxy/jupyter-matlab-proxy/install_guides/the-littlest-jupyterhub/tljh-matlab/README.md). 
+
+Use the plugin to install MATLAB, its dependencies, and the MATLAB integration for Jupyter in TLJH. 
+
+To install the MATLAB plugin, run the `bootstrap` script from your TLJH installation process again, and add the `tljh-matlab` plugin:
+
+```bash
+curl -L https://tljh.jupyter.org/bootstrap.py \
+ | sudo python3 - \
+   --plugin tljh-matlab
+```
+
+For more information on installing plugins into a TLJH environment, see [Customizing the Installer *(TLJH Docs)*](https://tljh.jupyter.org/en/latest/topic/customizing-installer.html#customizing-the-installer).
+
+To customize the MATLAB plugin, for example to choose which MATLAB toolboxes to install, see [MATLAB Plugin for The Littlest JupyterHub](https://github.com/mathworks/jupyter-matlab-proxy/tree/main/install_guides/the-littlest-jupyterhub/tljh-matlab/README.md).
+
+## Setting Up TLJH with MATLAB in Docker: Quick Demo
+
+Execute the [start-container-with-tljh-matlab.sh](./start-container-with-tljh-matlab.sh) script to efficiently set up a sample TLJH environment with MATLAB & The MATLAB Integration for Jupyter installed within a Docker container.
+
+```bash
+./start-container-with-tljh-matlab.sh
+```
+
+Once initialized, your JupyterHub server will be accessible for notebook hosting at **http://Your-FQDN:12000**. You can view it in your browser via **http://localhost:12000/**.
+
+To tailor the MATLAB release or to install different MATLAB toolboxes within the TLJH instance, adjust the environment variables in the [.matlab_env](./.matlab_env) file accordingly.
+
+## Learn More
+
+- [The Littlest JupyterHub Official Documentation (TLJH)](https://tljh.jupyter.org/en/stable/index.html).
+- [When to Use the Littlest JupyterHub (TLJH)](https://tljh.jupyter.org/en/stable/topic/whentouse.html).
+- [Plugins (TLJH)](https://tljh.jupyter.org/en/stable/contributing/plugins.html).
+
+
+----
+
+Copyright 2024 The MathWorks, Inc.
+
+----
+

install_guides/the-littlest-jupyterhub/start-container-with-tljh-matlab.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+# Copyright 2024 The MathWorks, Inc.
+# This script creates a container with The Littlest JupyterHub, and installs the MATLAB plugin tljh-matlab.
+# To modify the MATLAB installation, update the .matlab_env file
+# Update the last call to "docker exec" to customize your TLJH deployment.
+
+# Example invocation:
+# ./start-container-with-tljh-matlab.sh
+## for Local Development of tljh-matlab
+# ./start-container-with-tljh-matlab.sh --dev 1
+
+
+# Initialize DEV flag
+DEV=0
+
+# Function to display usage
+usage() {
+  echo "Usage: $0 [-d 1|0] <command> [arguments...]"
+  echo "  -d, --dev    Set development mode (1 for on, 0 for off). Default is OFF"
+  exit 1
+}
+
+# Parse the arguments
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    -d|--dev)
+      DEV="$2"
+      if [[ "$DEV" != "1" && "$DEV" != "0" ]]; then
+        echo "Error: DEV flag must be 1 or 0."
+        usage
+      fi
+      shift 2
+      ;;
+    -*|--*)
+      echo "Unknown option $1"
+      usage
+      ;;
+    *)
+      break
+      ;;
+  esac
+done
+
+set -e
+
+# # Get the current working directory
+CURRENT_DIR="$(pwd)"
+
+if [ $(dirname "$0") != '.' ]; then
+    PATH_TO_SCRIPTS="${CURRENT_DIR}/$(dirname "$0")"
+    echo "Changing directory to ... $PATH_TO_SCRIPTS"
+    pushd $PATH_TO_SCRIPTS
+fi
+
+# Create a Docker Container with systemd, named tljh-systemd
+docker build -t tljh-systemd -f https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/refs/heads/main/integration-tests/Dockerfile .
+
+# By default, the plugin is pulled from PyPI.
+MATLAB_PLUGIN_LOCATION="tljh-matlab"
+
+# Start the tljh-systemd
+docker run --privileged --detach --name=tljh-dev --publish 12000:80 --env-file .matlab_env tljh-systemd
+
+# Get the latest TLJH sources from GitHub and move the code into /srv/src as required by the instructions in :
+#   https://tljh.jupyter.org/en/latest/contributing/dev-setup.html
+docker exec tljh-dev sh -c "cd /srv && git clone --depth 1 https://github.com/jupyterhub/the-littlest-jupyterhub.git && mv the-littlest-jupyterhub src"
+
+if [ "$DEV" -eq 1 ]; then
+    echo "Development mode is ON."
+    MATLAB_PLUGIN_LOCATION="/tljh-matlab-local"    
+    # Copy plugin sources to writable location within the container.
+    docker container cp ./tljh-matlab tljh-dev:${MATLAB_PLUGIN_LOCATION}
+fi
+
+docker exec tljh-dev sh -c "python3 /srv/src/bootstrap/bootstrap.py --admin admin:password --plugin $MATLAB_PLUGIN_LOCATION"
+
+popd