Initial commit

Author: dpwrussell

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.

README.md

@@ -0,0 +1,54 @@
+
+# MATLAB Integration for Jupyter using VNC
+
+The `jupyter-matlab-vnc-proxy` Python® package allows you to integrate MATLAB® with Jupyter®. The MATLAB integration for Jupyter using VNC allows you to connect to a Linux® desktop, with MATLAB installed, from your Jupyter environment.
+
+If you have access to MATLAB R2020b or later, we recommend using the alternative package [`jupyter-matlab-proxy`](https://github.com/mathworks/jupyter-matlab-proxy) which comes with some limitations (see [Specifications and Limitations](https://www.mathworks.com/products/matlab-online/limitations.html)). This alternative enables you to open a MATLAB desktop in a web browser tab, directly from your Jupyter environment.
+
+## Use the MATLAB Integration for Jupyter using VNC
+
+Once you have a Jupyter environment with the `jupyter-matlab-vnc-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 VNC DESKTOP`. If you are using JupyterLab (on the right in figure below), select the `MATLAB VNC DESKTOP` icon on the launcher.
+
+<p align="center">
+  <img width="600" src="img/combined_launchers_vnc.png">
+</p>
+
+3. Wait for the Linux desktop to start. Reload the webpage if the connection fails to load.
+4. To use MATLAB, locate the MATLAB icon in the Linux desktop and double click on it and wait for it to start.
+
+## Installation
+
+If you want to install the `jupyter-matlab-vnc-proxy` package in a Jupyter Docker® image, see [Use MATLAB Integration for Jupyter using VNC in a Docker Container](https://github.com/mathworks-ref-arch/matlab-integration-for-jupyter/tree/main/matlab-vnc). Otherwise, if you want to install the `jupyter-matlab-vnc-proxy` package into a preexisting Jupyter environment, follow the instructions below.
+
+To install the `jupyter-matlab-vnc-proxy` package, follow these steps in your Jupyter environment:
+
+1. Install a MATLAB 64 bit Linux version. Make sure the the installation folder is on the system path.
+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-vnc/Dockerfile).
+3. Create the environment variable `NOVNC_PATH` and store in it the path to the [`noVNC`](https://github.com/novnc/noVNC) package installed in the previous step.
+4. Install the `jupyter-matlab-vnc-proxy` package by executing:
+
+   ```bash
+   python -m pip install https://github.com/mathworks/jupyter-matlab-vnc-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:
+
+```
+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).
+
+
+### Integration with JupyterHub
+
+If you want to use this integration with JupyterHub®, then you must install the `jupyter-matlab-vnc-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-vnc-proxy` Python package in a Docker image in the repository [Use MATLAB Integration for Jupyter using VNC in a Docker Container](https://github.com/mathworks-ref-arch/matlab-integration-for-jupyter/tree/main/matlab-vnc).
+
+
+## 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.

img/combined_launchers_vnc.png

@@ -0,0 +1,43 @@
+# Copyright 2020 The MathWorks, Inc.
+
+import os
+import shlex
+import tempfile
+
+def setup_desktop():
+    # Get path to noVNC installation through environment variables
+    NOVNC_PATH = os.getenv('NOVNC_PATH', '/opt/noVNC')
+    # make a secure temporary directory for sockets
+    # This is only readable, writeable & searchable by our uid
+    sockets_dir = tempfile.mkdtemp()
+    sockets_path = os.path.join(sockets_dir, 'vnc-socket')
+    vnc_command = ' '.join((shlex.quote(p) for p in [
+        'vncserver',
+        '-verbose',
+        '-xstartup', os.path.join(os.path.dirname(os.path.abspath(__file__)), 'resources', 'xstartup'),
+        '-geometry', '1680x1050',
+        '-SecurityTypes', 'None',
+        '-rfbunixpath', sockets_path,
+        '-fg',
+        ':1',
+    ]))
+    return {
+        'command': [
+            'websockify', '-v',
+            '--web', NOVNC_PATH,
+            '--heartbeat', '30',
+            '5901',
+            '--unix-target', sockets_path,
+            '--',
+            '/bin/sh', '-c',
+            f'cd {os.getcwd()} && {vnc_command}'
+        ],
+        'port': 5901,
+        'timeout': 30,
+        'mappath': {'/': '/mw_lite.html'},
+        'new_browser_window': True,
+        'launcher_entry': {
+            'title': 'MATLAB VNC DESKTOP',
+            'icon_path': os.path.join(os.path.dirname(os.path.abspath(__file__)), 'resources', 'matlab_icon.svg')
+        }
+    }

jupyter_matlab_vnc_proxy/__init__.py

@@ -0,0 +1,9 @@
+[Desktop Entry]
+Version=1.0
+Type=Application
+Name=MATLAB R2020b
+Exec=bash -c "python $HOME/.local/share/matlab_launcher.py"
+Icon=matlab_icon.png
+Terminal=false
+StartupNotify=true
+Categories=Development