Initial commit

Author: dpwrussell

.github/workflows/continuous-deployment.yml

@@ -0,0 +1,74 @@
+name: MATLAB Jupyter Integration
+
+on: [push]
+
+jobs:
+  node_app:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Use Node.js 13.x
+        uses: actions/setup-node@v1
+        with:
+          node-version: 13.x
+      - run: npm --prefix gui install gui
+      - run: npm run --prefix gui build --if-present
+      - run: npm --prefix gui test
+        env:
+          CI: true
+
+  python_app:
+    needs: node_app
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.6, 3.7, 3.8]
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install black pytest
+      - name: Lint with black
+        run: |
+          black --check .
+      - name: Test with pytest
+        run: |
+          pytest
+
+  python_app_wheel:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: python_app
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python 3.7
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.7
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install wheel
+      - name: Use Node.js 13.x
+        uses: actions/setup-node@v1
+        with:
+          node-version: 13.x
+      - name: Build wheel
+        run: |
+          python setup.py bdist_wheel
+      - name: Create Release
+        id: create_release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: ${{ github.ref }}
+          release_name: Release ${{ github.ref }}
+          body: Release ${{ github.ref }}
+          draft: false
+          prerelease: false

.gitignore

@@ -0,0 +1,6 @@
+*.egg-info/
+.eggs/
+__pycache__/
+build/
+dist/
+.venv/

Development_Customization_Info.md

@@ -0,0 +1,34 @@
+# Development Customization
+
+To develop the JavaScript Single-page application and Python application with live-reloading,
+start a development server for both.
+The JavaScript development server proxies all requests that it does not recognise
+to the Python development server.
+
+To start the JavaScript development server, execute:
+
+```bash
+# Change into the directory gui
+cd gui
+# Install the node dependencies
+npm install
+# Start the development server
+npm start
+```
+
+To start the Python development server, in a separate shell, execute:
+
+```bash
+# Create a Python virtual environment if one does not already exist (skip this step if one exists)
+python -m venv .venv
+# Activate the Python virtual environment (skip this if already done)
+source .venv/bin/activate
+# Install the Python package (and dependencies) in development mode (skip this if already done)
+pip install -e .[dev]
+# Start the development server
+DEV=true adev runserver jupyter_matlab_proxy/app.py
+```
+
+If you make any changes to either the JavaScript code or the Python code, then these apps will reload immediately showing the results. Bear in mind that this kind of live-reloading can have an impact on application state (on the serverside particularly). This occurs independently for the JavaScript and Python applications. So if you are working only on the frontend, the backend state will never be affected by changes to the frontend and vice-versa.
+
+In development mode, no MATLAB is required. Where MATLAB and Xvfb would have their processes launched, placeholder processes are launched in their stead.

LICENSE.md

@@ -0,0 +1,17 @@
+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) 2020, 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:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+2. 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.
+3. 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.

MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+recursive-include jupyter_matlab_proxy/icons *
+recursive-include jupyter_matlab_proxy/matlab *
+recursive-include gui *
+recursive-exclude gui/node_modules *
+recursive-exclude gui/build *

MATLAB_Licensing_Info.md

@@ -0,0 +1,39 @@
+# MATLAB Licensing Info
+
+
+**For End Users**:
+
+When starting MATLAB through this integration, you are presented with a user interface with two options to set up MATLAB licensing.
+
+<p align="center">
+  <img width="400" src="img/licensing_GUI.png">
+</p>
+
+To choose the right option, determine what MATLAB licenses you have access to. Your license must be current on [MathWorks® Software Maintenance Service](https://www.mathworks.com/services/maintenance.html). 
+
+
+
+If you are an academic user, you can use [this tool](https://www.mathworks.com/licensecenter/licenses/add) to determine if you have access to a campus-wide license through your institution. Otherwise, to see the licenses linked to your account, log in to your MathWorks account and go to [License Center](https://www.mathworks.com/licensecenter/?s_tid=hp_ff_s_license). You can link your MathWorks account with a license using [this tool](https://www.mathworks.com/licensecenter/licenses/add).
+
+
+
+Based on the license that you want to use, you can follow the procedures outlined in the table below to setup the MATLAB licensing for this integration.
+
+
+| License Type | Procedure |
+| ------ | ------ |
+| Individual (that only you use and is in your name; not a Home or Student)  | Your license is already configured for use with MATLAB Integration for Jupyter. Using the _Online License Manager_ tab, enter the credentials to your MathWorks account to get started.   |
+| Campus-Wide License | Your license is already configured for use with MATLAB Integration for Jupyter. Using the _Online License Manager_ tab, enter the credentials to your MathWorks account to get started.  |
+| Home and Student (that only you use and is in your name)  | These license types are not supported for use with MATLAB Integration for Jupyter.   |
+| Concurrent and Network Named User  | Using the _Network License Manager_ tab, enter the address to your organization’s network license manager. You can contact your license administrator* to find the address for the network license manager. |
+
+
+*Not sure who the license administrator is? Sign in to your [MathWorks Account](https://www.mathworks.com/mwaccount/), click the license you are using, then click the tab marked “Contact Administrators”.
+
+**For Administrators**
+
+
+| Scenario | License Type | Procedure |
+| ------ | ------ | ------ |
+| You want your users to use online licensing  | Campus-Wide, Individual  | These licenses are already configured for use with MATLAB Integration for Jupyter. When starting MATLAB, an end user will need to log in to their MathWorks account to use the license linked to it. |
+| You want your users to use licenses administered using a network license manager   | Campus-Wide, Concurrent, or Network Named User  | You will need to embed the address of your network license manager when deploying the integration for your Jupyter environment. Otherwise, an end user will need to manually enter the address to the network license manager when they start MATLAB. Each instance of MATLAB will consume a license seat. Using network named user licenses is possible but is *not recommended*. All named users will need to be explicitly specified in the license manager options file. Named users may not use MathWorks products on more than two computers simultaneously - specifying a single, generic named user for the integration will not be viable.   |

README.md

@@ -0,0 +1,87 @@
+# MATLAB Integration for Jupyter
+
+The `jupyter-matlab-proxy` Python® package allows you to integrate MATLAB® with Jupyter®. The MATLAB integration for Jupyter enables you to open a MATLAB desktop in a web browser tab, directly from your Jupyter environment. This is not a kernel integration.
+
+The MATLAB Integration for Jupyter is under active development and you might find issues with the MATLAB graphical user interface. For support or to report issues, see the [Feedback](#Feedback) section.
+
+
+## Use the MATLAB Integration for Jupyter
+
+Once you have a Jupyter environment with the `jupyter-matlab-proxy` package installed, to use the integration, follow these steps:
+
+1. Open your Jupyter environment.
+
+2. If you are using Jupyter Notebook (on the left in figure below), on the `New` menu, select `MATLAB`. If you are using JupyterLab (on the right in figure below), select the MATLAB icon on the launcher.
+
+<p align="center">
+  <img width="600" src="img/combined_launchers.png">
+</p>
+
+3. If prompted to do so, enter credentials for a MathWorks account associated with a MATLAB license. If you are using a network license manager, change to the _Network License Manager_ tab and enter the license server address instead. To determine the appropriate method for your license type, consult [MATLAB Licensing Info](./MATLAB_Licensing_Info.md).
+
+<p align="center">
+  <img width="400" src="img/licensing_GUI.png">
+</p>
+
+4. Wait for the MATLAB session to start. This can take several minutes.
+
+5. To manage the MATLAB integration for Jupyter, click the tools icon shown below.
+
+<p align="center">
+  <img width="100" src="img/tools_icon.png">
+</p>
+
+6. Clicking the tools icon opens a status panel with buttons like the ones below:
+
+    <p align="center">
+      <img width="800" src="img/status_panel.png">
+    </p>
+
+   The following options are available in the status panel (some options are only available in a specific context):
+
+   * Start MATLAB Session — Start your MATLAB session. Available if MATLAB is stopped.
+   * Restart MATLAB Session — Restart your MATLAB session. Available if MATLAB is running or starting.
+   * Stop MATLAB Session — Stop your MATLAB session. Use this option if you want to free up RAM and CPU resources. Available if MATLAB is running or starting.
+   * Sign Out — Sign out of MATLAB. Use this to stop MATLAB and sign in with an alternative account. Available if using online licensing.
+   * Unset License Server Address — Unset network license manager server address. Use this to stop MATLAB and enter new licensing information. Available if using network license manager.
+   * Feedback — Send feedback about the MATLAB Integration for Jupyter. This action opens your default email application.
+   * Help — Open a help pop-up for a detailed description of the options.
+
+
+## Installation
+
+The `jupyter-matlab-proxy` package requires a Linux® operating system.
+
+If you want to install this package in a Jupyter Docker® image, see [Use MATLAB Integration for Jupyter in a Docker Container](https://github.com/mathworks-ref-arch/matlab-integration-for-jupyter/tree/main/matlab). Otherwise, if you want to install the `jupyter-matlab-proxy` package into a preexisting Jupyter environment, follow the instructions below.
+
+To install the `jupyter-matlab-proxy` package, follow these steps in your Jupyter environment on a Linux OS:
+
+1. Install a MATLAB 64 bit Linux version. Make sure the the installation folder is on the system path. This integration supports MATLAB R2020b or later. For earlier versions, use the alternative [MATLAB Integration for Jupyter using VNC](https://github.com/mathworks/jupyter-matlab-vnc-proxy).
+2. Install software packages that MATLAB depends on and software packages that this integration depends on. For a list of required software packages in a Debian based distribution, inspect [this Dockerfile](https://github.com/mathworks-ref-arch/matlab-integration-for-jupyter/blob/main/matlab/Dockerfile).
+3. Install [Node and Node Package Manager](https://nodejs.org/en/) version 13 or higher.
+4. Install the `jupyter-matlab-proxy` package by executing:
+```bash
+python -m pip install https://github.com/mathworks/jupyter-matlab-proxy/archive/0.1.0.tar.gz
+```
+
+If you want to use this integration with JupyterLab®, you must also install `jupyterlab-server-proxy` JupyterLab extension. To install the extension, use the following command:
+
+``` bash
+jupyter labextension install @jupyterlab/server-proxy
+```
+
+For more information see [GUI Launchers](https://jupyter-server-proxy.readthedocs.io/en/latest/launchers.html#jupyterlab-launcher-extension).
+
+
+### Limitations
+
+This package supports the same subset of MATLAB features and commands as MATLAB Online. For a full list supported products and limitations, see [Specifications and Limitations](https://www.mathworks.com/products/matlab-online/limitations.html). For a list of browser requirements, see [Cloud Solutions Browser Requirements](https://www.mathworks.com/support/requirements/browser-requirements.html). If you need to use functionality that is not yet supported, you can leverage the alternative [MATLAB Integration for Jupyter using VNC](https://github.com/mathworks/jupyter-matlab-vnc-proxy).
+
+### Integration with JupyterHub
+
+If you want to use this integration with JupyterHub®, then you must 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, then install this package in the Docker image used to launch them. You can find a reference architecture that installs the `jupyter-matlab-proxy` Python package in a Docker image in the repository [Use MATLAB Integration for Jupyter in a Docker Container](https://github.com/mathworks-ref-arch/matlab-integration-for-jupyter/tree/main/matlab).
+
+
+## Feedback
+
+We encourage you to try this repository with your environment and provide feedback – the technical team is monitoring this repository. If you encounter a technical issue or have an enhancement request, send an email to `[email protected]`.

SECURITY.md

@@ -0,0 +1,6 @@
+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.

gui/.gitignore

@@ -0,0 +1,23 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# production
+/build
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

gui/README.md

@@ -0,0 +1,68 @@
+This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).
+
+## Available Scripts
+
+In the project directory, you can run:
+
+### `npm start`
+
+Runs the app in the development mode.<br />
+Open [http://localhost:3000](http://localhost:3000) to view it in the browser.
+
+The page will reload if you make edits.<br />
+You will also see any lint errors in the console.
+
+### `npm test`
+
+Launches the test runner in the interactive watch mode.<br />
+See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
+
+### `npm run build`
+
+Builds the app for production to the `build` folder.<br />
+It correctly bundles React in production mode and optimizes the build for the best performance.
+
+The build is minified and the filenames include the hashes.<br />
+Your app is ready to be deployed!
+
+See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.
+
+### `npm run eject`
+
+**Note: this is a one-way operation. Once you `eject`, you can’t go back!**
+
+If you aren’t satisfied with the build tool and configuration choices, you can `eject` at any time. This command will remove the single build dependency from your project.
+
+Instead, it will copy all the configuration files and the transitive dependencies (webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except `eject` will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own.
+
+You don’t have to ever use `eject`. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.
+
+## Learn More
+
+You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started).
+
+To learn React, check out the [React documentation](https://reactjs.org/).
+
+### Code Splitting
+
+This section has moved here: https://facebook.github.io/create-react-app/docs/code-splitting
+
+### Analyzing the Bundle Size
+
+This section has moved here: https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size
+
+### Making a Progressive Web App
+
+This section has moved here: https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app
+
+### Advanced Configuration
+
+This section has moved here: https://facebook.github.io/create-react-app/docs/advanced-configuration
+
+### Deployment
+
+This section has moved here: https://facebook.github.io/create-react-app/docs/deployment
+
+### `npm run build` fails to minify
+
+This section has moved here: https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify