From f9c0a9a52a255c8298cf50eccd1ec43aa6e3ea2a Mon Sep 17 00:00:00 2001 From: Prabhakar Kumar Date: Tue, 26 Nov 2024 06:29:27 +0000 Subject: [PATCH] Introducing `install_guide/the-littlest-jupyterhub` and the MATLAB plugin for TLJH. --- .github/workflows/publish-tljh-matlab.yml | 65 +++++++ .../workflows/test-jupyter-matlab-proxy.yml | 1 + .github/workflows/test-tljh-matlab.yml | 50 ++++++ README.md | 28 ++- SECURITY.md | 9 +- .../the-littlest-jupyterhub/.matlab_env | 3 + .../the-littlest-jupyterhub/README.md | 53 ++++++ .../start-container-with-tljh-matlab.sh | 77 +++++++++ .../tljh-matlab/.gitignore | 162 ++++++++++++++++++ .../tljh-matlab/LICENSE | 16 ++ .../tljh-matlab/README.md | 47 +++++ .../tljh-matlab/SECURITY.md | 11 ++ .../tljh-matlab/setup.py | 23 +++ .../tljh-matlab/src/__init__.py | 1 + .../tljh-matlab/src/tljh_matlab/__init__.py | 1 + .../bash_scripts/install-matlab.sh | 34 ++++ .../src/tljh_matlab/install_matlab.py | 34 ++++ .../src/tljh_matlab/tljh_matlab.py | 24 +++ 18 files changed, 630 insertions(+), 9 deletions(-) create mode 100644 .github/workflows/publish-tljh-matlab.yml create mode 100644 .github/workflows/test-tljh-matlab.yml create mode 100644 install_guides/the-littlest-jupyterhub/.matlab_env create mode 100644 install_guides/the-littlest-jupyterhub/README.md create mode 100755 install_guides/the-littlest-jupyterhub/start-container-with-tljh-matlab.sh create mode 100644 install_guides/the-littlest-jupyterhub/tljh-matlab/.gitignore create mode 100644 install_guides/the-littlest-jupyterhub/tljh-matlab/LICENSE create mode 100644 install_guides/the-littlest-jupyterhub/tljh-matlab/README.md create mode 100644 install_guides/the-littlest-jupyterhub/tljh-matlab/SECURITY.md create mode 100755 install_guides/the-littlest-jupyterhub/tljh-matlab/setup.py create mode 100644 install_guides/the-littlest-jupyterhub/tljh-matlab/src/__init__.py create mode 100755 install_guides/the-littlest-jupyterhub/tljh-matlab/src/tljh_matlab/__init__.py create mode 100755 install_guides/the-littlest-jupyterhub/tljh-matlab/src/tljh_matlab/bash_scripts/install-matlab.sh create mode 100644 install_guides/the-littlest-jupyterhub/tljh-matlab/src/tljh_matlab/install_matlab.py create mode 100755 install_guides/the-littlest-jupyterhub/tljh-matlab/src/tljh_matlab/tljh_matlab.py diff --git a/.github/workflows/publish-tljh-matlab.yml b/.github/workflows/publish-tljh-matlab.yml new file mode 100644 index 00000000..6cc8ff78 --- /dev/null +++ b/.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 diff --git a/.github/workflows/test-jupyter-matlab-proxy.yml b/.github/workflows/test-jupyter-matlab-proxy.yml index 9e752ecf..67c3a975 100644 --- a/.github/workflows/test-jupyter-matlab-proxy.yml +++ b/.github/workflows/test-jupyter-matlab-proxy.yml @@ -12,6 +12,7 @@ on: - "src/**" - "tests/**" - "setup.py" + jobs: call-unit-tests: # Run unit tests diff --git a/.github/workflows/test-tljh-matlab.yml b/.github/workflows/test-tljh-matlab.yml new file mode 100644 index 00000000..c1e751a7 --- /dev/null +++ b/.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 diff --git a/README.md b/README.md index f6dee348..b09cded0 100644 --- a/README.md +++ b/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). diff --git a/SECURITY.md b/SECURITY.md index e0429a24..15279508 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -3,4 +3,11 @@ Reporting Security Vulnerabilities If you believe you have discovered a security vulnerability, please report it to security@mathworks.com 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. \ No newline at end of file +for additional information. + +---- + +Copyright 2021-2024 The MathWorks, Inc. + +---- + diff --git a/install_guides/the-littlest-jupyterhub/.matlab_env b/install_guides/the-littlest-jupyterhub/.matlab_env new file mode 100644 index 00000000..7cc118e6 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/install_guides/the-littlest-jupyterhub/README.md b/install_guides/the-littlest-jupyterhub/README.md new file mode 100644 index 00000000..3fc5f917 --- /dev/null +++ b/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. + +---- + diff --git a/install_guides/the-littlest-jupyterhub/start-container-with-tljh-matlab.sh b/install_guides/the-littlest-jupyterhub/start-container-with-tljh-matlab.sh new file mode 100755 index 00000000..36a07459 --- /dev/null +++ b/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] [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 \ No newline at end of file diff --git a/install_guides/the-littlest-jupyterhub/tljh-matlab/.gitignore b/install_guides/the-littlest-jupyterhub/tljh-matlab/.gitignore new file mode 100644 index 00000000..efa407c3 --- /dev/null +++ b/install_guides/the-littlest-jupyterhub/tljh-matlab/.gitignore @@ -0,0 +1,162 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# poetry +# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. +# This is especially recommended for binary packages to ensure reproducibility, and is more +# commonly ignored for libraries. +# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control +#poetry.lock + +# pdm +# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. +#pdm.lock +# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it +# in version control. +# https://pdm.fming.dev/latest/usage/project/#working-with-version-control +.pdm.toml +.pdm-python +.pdm-build/ + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ + +# PyCharm +# JetBrains specific template is maintained in a separate JetBrains.gitignore that can +# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore +# and can be added to the global gitignore or merged into this file. For a more nuclear +# option (not recommended) you can uncomment the following to ignore the entire idea folder. +#.idea/ \ No newline at end of file diff --git a/install_guides/the-littlest-jupyterhub/tljh-matlab/LICENSE b/install_guides/the-littlest-jupyterhub/tljh-matlab/LICENSE new file mode 100644 index 00000000..5cdec65b --- /dev/null +++ b/install_guides/the-littlest-jupyterhub/tljh-matlab/LICENSE @@ -0,0 +1,16 @@ +MATHWORKS CLOUD REFERENCE ARCHITECTURE LICENSE + +The files in this GitHub repository refer to commercial software products and services, virtual machine images, and related materials of The MathWorks, Inc. (“MathWorks Programs”). MathWorks Programs are separately licensed under the MathWorks Software License Agreement, available in the desktop installation of the MathWorks Programs or in the virtual machine image. The files in this GitHub repository may also refer to third-party software licensed under separate terms provided by such third parties. + +The following license terms apply only to the files in this GitHub repository, including files in this folder and its subfolders, and do not apply to MathWorks Programs. References to “software” and “code” in the following license terms refer to the files in this GitHub repository. + +Copyright (c) 2024, The MathWorks, Inc. + +All rights reserved. + +Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: + +Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. +Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. +In all cases, the software is, and all modifications and derivatives of the software shall be, licensed to you solely for use in conjunction with MathWorks products and service offerings. +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. \ No newline at end of file diff --git a/install_guides/the-littlest-jupyterhub/tljh-matlab/README.md b/install_guides/the-littlest-jupyterhub/tljh-matlab/README.md new file mode 100644 index 00000000..e52e6a1a --- /dev/null +++ b/install_guides/the-littlest-jupyterhub/tljh-matlab/README.md @@ -0,0 +1,47 @@ +# MATLAB Plugin for The Littlest JupyterHub + +A plugin for running [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). + +## Background + +The Littlest JupyterHub supports [plugins](https://tljh.jupyter.org/en/latest/contributing/plugins.html) that provide additional features. The MATLAB plugin for TLJH, `tljh-matlab`, installs: +* a specified version of MATLAB, as well as any MATLAB toolboxes +* the system libraries that MATLAB requires +* the [MATLAB Integration for Jupyter](github.com/mathworks/jupyter-matlab-proxy), for running MATLAB in Jupyter notebooks and accessing the MATLAB environment from Jupyter. + +## Usage +To install the MATLAB plugin for TLJH include `--plugin tljh-matlab` in the Installer Script. +See [Customizing the Installer](https://tljh.jupyter.org/en/latest/topic/customizing-installer.html) for more information. + +For example, the following command sets up an `admin_user` with `admin_password` and installs `tljh-matlab`: +```bash +curl -L https://tljh.jupyter.org/bootstrap.py + | sudo python3 - \ + --admin admin_user:admin_password \ + --plugin tljh-matlab +``` + +## Customization +To customize the default values used by the plugin, set the relevant environment variables before using the bootstrap command: + +| Environment Variable Name | Default Values | Notes | +|---|---|---| +| MATLAB_RELEASE | R2024b | Specify the MATLAB release you would like to install. | +| MATLAB_PRODUCT_LIST | "MATLAB Symbolic_Math_Toolbox" | Specify a product by consulting the `--products` section of [MATLAB Package Manager](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/MPM.md). For example, to install Simulink in addition to MATLAB, use `"MATLAB Simulink"`. | +| MATLAB_INSTALL_DESTINATION | /opt/matlab/R2024b | Specify the path to the location where you want to install MATLAB. | + + +For example, to customize the plugin to install MATLAB R2023b and Simulink, run: +```bash +curl https://tljh.jupyter.org/bootstrap.py + | env MATLAB_RELEASE=R2023b MATLAB_PRODUCT_LIST="MATLAB Simulink" \ + sudo python3 - \ + --admin admin_user:admin_password \ + --plugin tljh-matlab +``` + +---- + +Copyright 2024 The MathWorks, Inc. + +---- \ No newline at end of file diff --git a/install_guides/the-littlest-jupyterhub/tljh-matlab/SECURITY.md b/install_guides/the-littlest-jupyterhub/tljh-matlab/SECURITY.md new file mode 100644 index 00000000..5a04f5b3 --- /dev/null +++ b/install_guides/the-littlest-jupyterhub/tljh-matlab/SECURITY.md @@ -0,0 +1,11 @@ +# Reporting Security Vulnerabilities + +If you believe you have discovered a security vulnerability, please report it to +[security@mathworks.com](mailto:security@mathworks.com). For more information, see [MathWorks Vulnerability Disclosure Policy for Security Researchers](https://www.mathworks.com/company/aboutus/policies_statements/vulnerability-disclosure-policy.html). + +---- + +Copyright 2024 The MathWorks, Inc. + +---- + diff --git a/install_guides/the-littlest-jupyterhub/tljh-matlab/setup.py b/install_guides/the-littlest-jupyterhub/tljh-matlab/setup.py new file mode 100755 index 00000000..36bd9588 --- /dev/null +++ b/install_guides/the-littlest-jupyterhub/tljh-matlab/setup.py @@ -0,0 +1,23 @@ +# Copyright 2024 The MathWorks, Inc. +from setuptools import setup, find_namespace_packages +from pathlib import Path + +HERE = Path(__file__).parent.resolve() +long_description = (HERE / "README.md").read_text() + +setup( + name="tljh-matlab", + entry_points={"tljh": ["matlab = tljh_matlab.tljh_matlab"]}, + version="0.1.0", + packages=find_namespace_packages(where="src"), + package_dir={"": "src"}, + package_data={"tljh_matlab.bash_scripts": ["*.sh"]}, + include_package_data=True, + long_description=long_description, + long_description_content_type="text/markdown", + url="https://github.com/mathworks/jupyter-matlab-proxy/tree/main/install_guides/the-littlest-jupyterhub/tljh-matlab", + author="The MathWorks, Inc.", + author_email="cloud@mathworks.com", + license="MATHWORKS CLOUD REFERENCE ARCHITECTURE LICENSE", + description="TLJH plugin for MATLAB", +) diff --git a/install_guides/the-littlest-jupyterhub/tljh-matlab/src/__init__.py b/install_guides/the-littlest-jupyterhub/tljh-matlab/src/__init__.py new file mode 100644 index 00000000..e16198d9 --- /dev/null +++ b/install_guides/the-littlest-jupyterhub/tljh-matlab/src/__init__.py @@ -0,0 +1 @@ +# Copyright 2024 The MathWorks, Inc. diff --git a/install_guides/the-littlest-jupyterhub/tljh-matlab/src/tljh_matlab/__init__.py b/install_guides/the-littlest-jupyterhub/tljh-matlab/src/tljh_matlab/__init__.py new file mode 100755 index 00000000..e16198d9 --- /dev/null +++ b/install_guides/the-littlest-jupyterhub/tljh-matlab/src/tljh_matlab/__init__.py @@ -0,0 +1 @@ +# Copyright 2024 The MathWorks, Inc. diff --git a/install_guides/the-littlest-jupyterhub/tljh-matlab/src/tljh_matlab/bash_scripts/install-matlab.sh b/install_guides/the-littlest-jupyterhub/tljh-matlab/src/tljh_matlab/bash_scripts/install-matlab.sh new file mode 100755 index 00000000..15bc983e --- /dev/null +++ b/install_guides/the-littlest-jupyterhub/tljh-matlab/src/tljh_matlab/bash_scripts/install-matlab.sh @@ -0,0 +1,34 @@ +#!/bin/bash +# Copyright 2024 The MathWorks, Inc. + +# Example invocation: +# subprocess.run(["bash", "install-matlab.sh"], +# env={"MATLAB_RELEASE":"R2024b", "MATLAB_PRODUCT_LIST":"MATLAB Simulink"}) + +# Set the default release to R2024b. +MATLAB_RELEASE="${MATLAB_RELEASE:-"R2024b"}" +# Uppercase first letter +MATLAB_RELEASE=${MATLAB_RELEASE^} + +# Set the default product list to only install MATLAB. +MATLAB_PRODUCT_LIST="${MATLAB_PRODUCT_LIST:-"MATLAB Symbolic_Math_Toolbox"}" + +MATLAB_INSTALL_DESTINATION="${MATLAB_INSTALL_DESTINATION:-"/opt/matlab/${MATLAB_RELEASE}"}" + +echo "Installing..." +echo "MATLAB_RELEASE: $MATLAB_RELEASE" +echo "MATLAB_PRODUCT_LIST: $MATLAB_PRODUCT_LIST" +echo "MATLAB_INSTALL_DESTINATION: $MATLAB_INSTALL_DESTINATION" + +env DEBIAN_FRONTEND="noninteractive" TZ="Etc/UTC" && apt-get update && apt-get install -y \ + ca-certificates \ + git \ + unzip \ + wget \ + xvfb \ + && git clone --depth 1 https://github.com/mathworks/devcontainer-features \ + && env RELEASE="${MATLAB_RELEASE}" PRODUCTS="${MATLAB_PRODUCT_LIST}" DESTINATION="${MATLAB_INSTALL_DESTINATION}" \ + ./devcontainer-features/src/matlab/install.sh \ + && ln -s ${MATLAB_INSTALL_DESTINATION}/bin/matlab /usr/bin/matlab + +# TLJH users dont have /usr/local/bin on the PATH, linking MATLAB into /usr/bin instead. \ No newline at end of file diff --git a/install_guides/the-littlest-jupyterhub/tljh-matlab/src/tljh_matlab/install_matlab.py b/install_guides/the-littlest-jupyterhub/tljh-matlab/src/tljh_matlab/install_matlab.py new file mode 100644 index 00000000..96f14463 --- /dev/null +++ b/install_guides/the-littlest-jupyterhub/tljh-matlab/src/tljh_matlab/install_matlab.py @@ -0,0 +1,34 @@ +# Copyright 2024 The MathWorks, Inc. + +import subprocess +import os + +# @package install_matlab +# This module provides functionalities to install MATLAB using a bash script. + + +def install_matlab_impl(): + """ + @brief Installs MATLAB using a predefined bash script. + + This function constructs the path to a bash script responsible for installing MATLAB and executes it. + The MATLAB release and product list are specified through environment variables. If not present, defaults are used. + + @param None + @return None + """ + # Construct the path to the install script + script = os.path.join(os.path.dirname(__file__), "bash_scripts/install-matlab.sh") + + # Call the bash script with environment variables + subprocess.run( + [ + "bash", + script, + ], + env=os.environ, + ) + + +if __name__ == "__main__": + install_matlab_impl() diff --git a/install_guides/the-littlest-jupyterhub/tljh-matlab/src/tljh_matlab/tljh_matlab.py b/install_guides/the-littlest-jupyterhub/tljh-matlab/src/tljh_matlab/tljh_matlab.py new file mode 100755 index 00000000..dc8f478e --- /dev/null +++ b/install_guides/the-littlest-jupyterhub/tljh-matlab/src/tljh_matlab/tljh_matlab.py @@ -0,0 +1,24 @@ +# Copyright 2024 The MathWorks, Inc. + +""" +MATLAB plugin that installs MATLAB, its dependencies and the MATLAB Integration for Jupyter +""" + +from tljh.hooks import hookimpl +from . import install_matlab + + +@hookimpl +def tljh_extra_user_pip_packages(): + return ["jupyter-matlab-proxy"] + + +@hookimpl +def tljh_post_install(): + """ + Post install script to be executed after installation + and after all the other hooks. + + This can be arbitrary Python code. + """ + install_matlab.install_matlab_impl()