Skip to content

Commit f9c0a9a

Browse files
prabhakk-mwprabhakk-mw
committed
Introducing install_guide/the-littlest-jupyterhub and the MATLAB plugin for TLJH.
1 parent 0c1b78c commit f9c0a9a

18 files changed

+630
-9
lines changed

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

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Copyright 2024 The MathWorks, Inc.
2+
name: Upload Python Package for tljh-matlab
3+
4+
on:
5+
release:
6+
types: [published]
7+
8+
permissions:
9+
contents: read
10+
11+
jobs:
12+
build-tljh-matlab:
13+
# Only run job if release tag contains `tljh-matlab`
14+
if: ${{ contains(github.ref, 'tljh-matlab') }}
15+
16+
runs-on: ubuntu-latest
17+
defaults:
18+
run:
19+
working-directory: ./install_guides/the-littlest-jupyterhub/tljh-matlab
20+
21+
steps:
22+
- uses: actions/checkout@v4
23+
24+
- name: Set up Python
25+
uses: actions/setup-python@v3
26+
with:
27+
python-version: '3.x'
28+
29+
- name: Install dependencies
30+
run: |
31+
python -m pip install --upgrade pip
32+
pip install build
33+
34+
- name: Build package
35+
run: |
36+
python -m build
37+
38+
- name: Upload distributions
39+
uses: actions/upload-artifact@v4
40+
with:
41+
name: release-dists
42+
path: install_guides/the-littlest-jupyterhub/tljh-matlab/dist/
43+
44+
release-tljh-matlab:
45+
runs-on: ubuntu-latest
46+
needs:
47+
- build-tljh-matlab
48+
permissions:
49+
# IMPORTANT: this permission is mandatory for trusted publishing
50+
id-token: write
51+
environment:
52+
name: pypi
53+
url: https://pypi.org/project/tljh-matlab
54+
55+
steps:
56+
- name: Retrieve release distributions
57+
uses: actions/download-artifact@v4
58+
with:
59+
name: release-dists
60+
path: install_guides/the-littlest-jupyterhub/tljh-matlab/dist/
61+
62+
- name: Publish to PyPI.
63+
uses: pypa/gh-action-pypi-publish@release/v1
64+
with:
65+
packages-dir: install_guides/the-littlest-jupyterhub/tljh-matlab/dist

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ on:
1212
- "src/**"
1313
- "tests/**"
1414
- "setup.py"
15+
1516
jobs:
1617
call-unit-tests:
1718
# Run unit tests

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

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Copyright 2024 The MathWorks, Inc.
2+
name: Test TLJH-MATLAB package
3+
4+
on:
5+
push:
6+
branches: [ "main" ]
7+
paths:
8+
# Only run tests when there are changes to these folders
9+
- "./install_guides/the-littlest-jupyterhub/tljh-matlab/**"
10+
11+
permissions:
12+
contents: read
13+
14+
jobs:
15+
build:
16+
17+
runs-on: ubuntu-latest
18+
19+
steps:
20+
- uses: actions/checkout@v4
21+
- name: Set up Python 3.10
22+
uses: actions/setup-python@v3
23+
with:
24+
python-version: "3.10"
25+
26+
- name: Install dependencies
27+
run: |
28+
python -m pip install --upgrade pip
29+
pip install flake8 black
30+
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
31+
32+
- name: Install Package
33+
run: |
34+
cd ./install_guides/the-littlest-jupyterhub/tljh-matlab
35+
python -m pip install .
36+
37+
- name: Lint with flake8
38+
run: |
39+
cd ./install_guides/the-littlest-jupyterhub/tljh-matlab
40+
# stop the build if there are Python syntax errors or undefined names
41+
flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
42+
# exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
43+
flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
44+
45+
- name: Lint with black
46+
run: black --check ./install_guides/the-littlest-jupyterhub/tljh-matlab
47+
48+
# - name: Test with unittest
49+
# run: |
50+
# python -m unittest discover --verbose -s ./install_guides/the-littlest-jupyterhub/tljh-matlab

‎README.md

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,23 @@ Run MATLAB® code in Jupyter® environments such as Jupyter notebooks, JupyterLa
88

99

1010
## Table of Contents
11-
1. [Features of MATLAB Integration _for Jupyter_](#features-of-matlab-integration-for-jupyter)
12-
2. [Requirements](#requirements)
13-
3. [Install](#install)
14-
4. [Get Started](#get-started)
15-
1. [Run MATLAB Code in a Jupyter Notebook](#run-matlab-code-in-a-jupyter-notebook)
16-
2. [Open MATLAB in a Browser](#open-matlab-in-a-browser)
17-
3. [Edit MATLAB Files in JupyterLab](#edit-matlab-files-in-jupyterlab)
18-
5. [Limitations](#limitations)
11+
- [MATLAB Integration _for Jupyter_](#matlab-integration-for-jupyter)
12+
- [Table of Contents](#table-of-contents)
13+
- [Features of MATLAB Integration _for Jupyter_](#features-of-matlab-integration-for-jupyter)
14+
- [Requirements](#requirements)
15+
- [Install](#install)
16+
- [Install from PyPI](#install-from-pypi)
17+
- [Build from Source](#build-from-source)
18+
- [Using JupyterHub](#using-jupyterhub)
19+
- [Using JupyterHub and The Littlest JupyterHub](#using-jupyterhub-and-the-littlest-jupyterhub)
20+
- [Using Simulink](#using-simulink)
21+
- [Troubleshooting](#troubleshooting)
22+
- [Get Started](#get-started)
23+
- [Run MATLAB Code in a Jupyter Notebook](#run-matlab-code-in-a-jupyter-notebook)
24+
- [Notes](#notes)
25+
- [Open MATLAB in a Browser](#open-matlab-in-a-browser)
26+
- [Edit MATLAB Files in JupyterLab](#edit-matlab-files-in-jupyterlab)
27+
- [Limitations](#limitations)
1928

2029

2130
## Features of MATLAB Integration _for Jupyter_
@@ -81,9 +90,12 @@ python -m pip install .
8190
```
8291

8392
### Using JupyterHub
93+
### Using JupyterHub and The Littlest JupyterHub
8494

8595
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).
8696

97+
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.
98+
8799
### Using Simulink
88100

89101
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

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,11 @@ Reporting Security Vulnerabilities
33
If you believe you have discovered a security vulnerability, please report it to
44
[email protected] instead of GitHub. Please see
55
[MathWorks Vulnerability Disclosure Policy for Security Researchers](https://www.mathworks.com/company/aboutus/policies_statements/vulnerability-disclosure-policy.html)
6-
for additional information.
6+
for additional information.
7+
8+
----
9+
10+
Copyright 2021-2024 The MathWorks, Inc.
11+
12+
----
13+

‎install_guides/the-littlest-jupyterhub/.matlab_env

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
MATLAB_RELEASE=R2024b
2+
MATLAB_PRODUCT_LIST=MATLAB Symbolic_Math_Toolbox
3+
MATLAB_INSTALL_DESTINATION=/opt/matlab/testing

‎install_guides/the-littlest-jupyterhub/README.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# MATLAB Integration for Jupyter on The Littlest JupyterHub
2+
3+
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.
4+
5+
6+
## Set up TLJH
7+
8+
The [TLJH Documentation](https://tljh.jupyter.org/en/stable/install/index.html) contains instructions for installing TLJH in different environments.
9+
10+
Once you have a working TLJH stack, you can add MATLAB into your TLJH stack using the MATLAB Plugin for The Littlest JupyterHub.
11+
12+
## Add MATLAB to TLJH Installation
13+
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).
14+
15+
Use the plugin to install MATLAB, its dependencies, and the MATLAB integration for Jupyter in TLJH.
16+
17+
To install the MATLAB plugin, run the `bootstrap` script from your TLJH installation process again, and add the `tljh-matlab` plugin:
18+
19+
```bash
20+
curl -L https://tljh.jupyter.org/bootstrap.py \
21+
| sudo python3 - \
22+
--plugin tljh-matlab
23+
```
24+
25+
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).
26+
27+
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).
28+
29+
## Setting Up TLJH with MATLAB in Docker: Quick Demo
30+
31+
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.
32+
33+
```bash
34+
./start-container-with-tljh-matlab.sh
35+
```
36+
37+
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/**.
38+
39+
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.
40+
41+
## Learn More
42+
43+
- [The Littlest JupyterHub Official Documentation (TLJH)](https://tljh.jupyter.org/en/stable/index.html).
44+
- [When to Use the Littlest JupyterHub (TLJH)](https://tljh.jupyter.org/en/stable/topic/whentouse.html).
45+
- [Plugins (TLJH)](https://tljh.jupyter.org/en/stable/contributing/plugins.html).
46+
47+
48+
----
49+
50+
Copyright 2024 The MathWorks, Inc.
51+
52+
----
53+

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

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
#!/bin/bash
2+
# Copyright 2024 The MathWorks, Inc.
3+
# This script creates a container with The Littlest JupyterHub, and installs the MATLAB plugin tljh-matlab.
4+
# To modify the MATLAB installation, update the .matlab_env file
5+
# Update the last call to "docker exec" to customize your TLJH deployment.
6+
7+
# Example invocation:
8+
# ./start-container-with-tljh-matlab.sh
9+
## for Local Development of tljh-matlab
10+
# ./start-container-with-tljh-matlab.sh --dev 1
11+
12+
13+
# Initialize DEV flag
14+
DEV=0
15+
16+
# Function to display usage
17+
usage() {
18+
echo "Usage: $0 [-d 1|0] <command> [arguments...]"
19+
echo " -d, --dev Set development mode (1 for on, 0 for off). Default is OFF"
20+
exit 1
21+
}
22+
23+
# Parse the arguments
24+
while [[ $# -gt 0 ]]; do
25+
case $1 in
26+
-d|--dev)
27+
DEV="$2"
28+
if [[ "$DEV" != "1" && "$DEV" != "0" ]]; then
29+
echo "Error: DEV flag must be 1 or 0."
30+
usage
31+
fi
32+
shift 2
33+
;;
34+
-*|--*)
35+
echo "Unknown option $1"
36+
usage
37+
;;
38+
*)
39+
break
40+
;;
41+
esac
42+
done
43+
44+
set -e
45+
46+
# # Get the current working directory
47+
CURRENT_DIR="$(pwd)"
48+
49+
if [ $(dirname "$0") != '.' ]; then
50+
PATH_TO_SCRIPTS="${CURRENT_DIR}/$(dirname "$0")"
51+
echo "Changing directory to ... $PATH_TO_SCRIPTS"
52+
pushd $PATH_TO_SCRIPTS
53+
fi
54+
55+
# Create a Docker Container with systemd, named tljh-systemd
56+
docker build -t tljh-systemd -f https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/refs/heads/main/integration-tests/Dockerfile .
57+
58+
# By default, the plugin is pulled from PyPI.
59+
MATLAB_PLUGIN_LOCATION="tljh-matlab"
60+
61+
# Start the tljh-systemd
62+
docker run --privileged --detach --name=tljh-dev --publish 12000:80 --env-file .matlab_env tljh-systemd
63+
64+
# Get the latest TLJH sources from GitHub and move the code into /srv/src as required by the instructions in :
65+
# https://tljh.jupyter.org/en/latest/contributing/dev-setup.html
66+
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"
67+
68+
if [ "$DEV" -eq 1 ]; then
69+
echo "Development mode is ON."
70+
MATLAB_PLUGIN_LOCATION="/tljh-matlab-local"
71+
# Copy plugin sources to writable location within the container.
72+
docker container cp ./tljh-matlab tljh-dev:${MATLAB_PLUGIN_LOCATION}
73+
fi
74+
75+
docker exec tljh-dev sh -c "python3 /srv/src/bootstrap/bootstrap.py --admin admin:password --plugin $MATLAB_PLUGIN_LOCATION"
76+
77+
popd

0 commit comments

Comments
 (0)