forked from mathworks/jupyter-matlab-proxy
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Introducing install_guide/the-littlest-jupyterhub and a TLJH Plugin f…
…or MATLAB called tljh-matlab
- Loading branch information
1 parent
1d5eff3
commit 820c6f2
Showing
17 changed files
with
768 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,35 @@ | ||
| # Copyright 2024 The MathWorks, Inc. | ||
| name: Upload Python Package for tljh-matlab | ||
|
|
||
| on: | ||
| release: | ||
| types: [published] | ||
|
|
||
| permissions: | ||
| contents: read | ||
| id-token: write | ||
|
|
||
| jobs: | ||
| deploy: | ||
|
|
||
| runs-on: ubuntu-latest | ||
|
|
||
| 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 | ||
| cd ./install_guides/the-littlest-jupyterhub/tljh-matlab | ||
| pip install build | ||
| - name: Build package | ||
| run: python -m build | ||
|
|
||
| - name: Publish to PyPI. | ||
| uses: pypa/gh-action-pypi-publish@release/v1 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| # Copyright 2024 The MathWorks, Inc. | ||
| name: Test TLJH-MATLAB package | ||
|
|
||
| on: | ||
| push: | ||
| branches: [ "main" ] | ||
| pull_request: | ||
| branches: [ "main" ] | ||
|
|
||
| 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: | | ||
| # 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 . | ||
|
|
||
| - name: Test with unittest | ||
| run: | | ||
| python -m unittest discover --verbose |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,87 @@ | ||
| # Running MATLAB Integration for Jupyter on The Littlest JupyterHub in a Docker Container | ||
|
|
||
| This guide customizes a **"The Littlest JupyterHub"** aka **TLJH** stack to include MATLAB, its dependencies and the MATLAB Integration for Jupyter. | ||
|
|
||
| **TLJH** can run on several modern linux environments. For a full listing for the supported environements, See [Installing (TLJH)](https://tljh.jupyter.org/en/stable/install/index.html). | ||
|
|
||
| The rest of this document will use the [Setting up Development Environment (TLJH)](https://tljh.jupyter.org/en/stable/contributing/dev-setup.html) to install TLJH in a Docker Container and customize it to include MATLAB and the MATLAB Integration for Jupyter. | ||
|
|
||
| When completed, you will have access to a JupyterHub server running from within your Docker container, capable of serving Jupyter Notebook Servers for multiple users at `http://Your-FQDN:12000` | ||
|
|
||
| Customize it to include MATLAB and the MATLAB Integration for Jupyter with the plugin `tljh-matlab` using the following command: | ||
|
|
||
| ```bash | ||
| python3 /srv/src/bootstrap/bootstrap.py --admin admin:password --plugin tljh-matlab | ||
| ``` | ||
|
|
||
| ### Table of Contents | ||
| 1. [Set up TLJH with Docker](#set-up-tljh-with-docker) | ||
| 2. [Customize Installation to include MATLAB](#customize-installation-to-include-matlab) | ||
|
|
||
|
|
||
| ## Set up TLJH with Docker | ||
|
|
||
| The following lines are taken directly from [Setting up Development Environment (TLJH)](https://tljh.jupyter.org/en/stable/contributing/dev-setup.html) for your convenience. We **highly** recommend following the instruction directly from the link above. | ||
|
|
||
| > The easiest & safest way to develop & test TLJH is with [Docker](https://www.docker.com/). | ||
| > | ||
| > 1. Install Docker Community Edition by following the instructions on [their website](https://www.docker.com/community-edition). | ||
| > 1. Clone the [git repo](https://github.com/jupyterhub/the-littlest-jupyterhub) (or your fork of it). | ||
| > | ||
| > 1. Build a docker image that has a functional systemd in it. | ||
| > ```bash | ||
| > git clone https://github.com/jupyterhub/the-littlest-jupyterhub && cd the-littlest-jupyterhub | ||
| > docker build -t tljh-systemd . -f integration-tests/Dockerfile | ||
| > ``` | ||
| > 1. Run a docker container with the image in the background, while bind mounting your TLJH repository under `/srv/src`. | ||
| > ```bash | ||
| > docker run \ | ||
| > --privileged \ | ||
| > --detach \ | ||
| > --name=tljh-dev \ | ||
| > --publish 12000:80 \ | ||
| > --mount type=bind,source="$(pwd)",target=/srv/src \ | ||
| > tljh-systemd | ||
| > ``` | ||
| > 1. Get a shell inside the running docker container. | ||
| > ```bash | ||
| > docker exec -it tljh-dev /bin/bash | ||
| > ``` | ||
| > 1. Run the bootstrapper from inside the container (see step above): The container image is already set up to default to a `dev` install, so it’ll install from your local repo rather than from github. | ||
| > ```bash | ||
| > python3 /srv/src/bootstrap/bootstrap.py --admin admin | ||
| > ``` | ||
| > 1. Or, if you would like to setup the admin’s password during install, you can use this command (replace “admin” with the desired admin username and “password” with the desired admin password): | ||
| > ```bash | ||
| > python3 /srv/src/bootstrap/bootstrap.py --admin admin:password | ||
| > ``` | ||
| > | ||
| > The primary hub environment will also be in your PATH already for convenience. | ||
| > | ||
| > You should be able to access the JupyterHub from your browser now at http://localhost:12000. | ||
| > | ||
| > **Congratulations**, you are set up to develop TLJH! | ||
| > | ||
| ## Customize Installation to include MATLAB | ||
| TLJH can install additional *plugins* to customize the installation. | ||
| See [Installing TLJH plugins](https://tljh.jupyter.org/en/stable/topic/customizing-installer.html) for more information. | ||
| This repository publishes a python package `tljh-matlab` which installs MATLAB, its dependencies and the MATLAB integration for Jupyter into TLJH. | ||
| To install the plugin, run the `bootstrap.py` script in `step 6.` from the previous section, as shown below: | ||
| ```bash | ||
| python3 /srv/src/bootstrap/bootstrap.py --admin admin:password --plugin tljh-matlab | ||
| ``` | ||
| Customize it using `tljh-matlab` ([TLJH Plugin](https://tljh.jupyter.org/en/stable/contributing/plugins.html) for MATLAB) | ||
| ## Background Reading | ||
| ### TLJH | ||
| A simple JupyterHub distribution for a small (0-100) number of users on a single server. | ||
| Refer to the official documentation of [The Littlest JupyterHub](https://tljh.jupyter.org/en/stable/index.html) for more information on capabilities and installation guides. | ||
| We recommend reading [When to use The Littlest JupyterHub](https://tljh.jupyter.org/en/stable/topic/whentouse.html) to determine if TLJH right tool for you. |
162 changes: 162 additions & 0 deletions
162
install_guides/the-littlest-jupyterhub/tljh-matlab/.gitignore
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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/ |
16 changes: 16 additions & 0 deletions
16
install_guides/the-littlest-jupyterhub/tljh-matlab/LICENSE
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
40 changes: 40 additions & 0 deletions
40
install_guides/the-littlest-jupyterhub/tljh-matlab/README.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,40 @@ | ||
| # tljh-matlab | ||
|
|
||
| TLJH plugin for [The Littlest JupyterHub](https://tljh.jupyter.org/) that installs MATLAB, and the MATLAB Integration for Jupyter. | ||
|
|
||
| The [Littlest JupyterHub installation](https://tljh.jupyter.org/en/latest/topic/customizing-installer.html#installing-tljh-plugins) can install **plugins** that provide additional features, in the JupyterHub stack being provisioned. | ||
|
|
||
| The `tljh-matlab` plugin installs: | ||
| * A specified version of MATLAB | ||
| * The system libraries required by MATLAB | ||
| * The MATLAB Integration for Jupyter, to enable the usage of MATLAB via Notebooks, and to access the MATLAB desktop from Jupyter. See [jupyter-matlab-proxy](github.com/mathworks/jupyter-matlab-proxy) for more information. | ||
|
|
||
|
|
||
| Command to install plugin: | ||
| ```bash | ||
| docker run --privileged --detach --name=tljh-dev --publish 12000:80 --mount type=bind,source="$(pwd)",target=/srv/src tljh-systemd | ||
| docker exec -it tljh-dev /bin/bash | ||
| python3 /srv/src/bootstrap/bootstrap.py --admin admin:password --plugin tljh-matlab | ||
| ``` | ||
|
|
||
| To customize the default values used by the plugin , set the appropriate environment variable before the `bootstrap` command | ||
|
|
||
| | Environment Variable Name | Default Values | Notes| | ||
| |--|--|--| | ||
| | MATLAB_RELEASE | R2024a | Specify the MATLAB release you would like to install | | ||
| | MATLAB_PRODUCT_LIST | "MATLAB Symbolic_Math_Toolbox" | See `--products` section of [MPM.md](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/MPM.md) for information on the supported products and their name specification. For example to install Simulink along with MATLAB use `"MATLAB Simulink"` | | ||
| |MATLAB_INSTALL_DESTINATION| /opt/matlab/R2024a | Specify the path to the location you would like to install MATLAB | | ||
| | OS | ubuntu22.04 | See [matlab-deps](https://github.com/mathworks-ref-arch/container-images/tree/main/matlab-deps/r2024a) for the list of supported OS values by Release.| | ||
|
|
||
| Example: | ||
| ```bash | ||
| env MATLAB_RELEASE=R2023b MATLAB_PRODUCT_LIST="MATLAB Simulink" python3 /srv/src/bootstrap/bootstrap.py --admin admin:password --plugin tljh-matlab | ||
| ``` | ||
|
|
||
|
|
||
|
|
||
| ---- | ||
|
|
||
| Copyright 2024 The MathWorks, Inc. | ||
|
|
||
| ---- |
Oops, something went wrong.