Skip to content

Commit a649591

Browse files
dpwrusselldpwrussell
committed
Initial commit
0 parents  commit a649591

File tree

11 files changed

+652
-0
lines changed

11 files changed

+652
-0
lines changed

‎LICENSE.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
MATHWORKS CLOUD REFERENCE ARCHITECTURE LICENSE
2+
3+
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.
4+
5+
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.
6+
7+
Copyright (c) 2020, The MathWorks, Inc.
8+
9+
All rights reserved.
10+
11+
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
12+
13+
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
14+
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.
15+
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.
16+
17+
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

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# MATLAB Integration for Jupyter
2+
3+
This repository contains two possible solutions for running Jupyter® with MATLAB® integration, inside a Docker® container:
4+
5+
1. Use MATLAB Integration for Jupyter in a Docker Container (matlab)
6+
7+
2. Use MATLAB Integration for Jupyter using VNC in a Docker Container (matlab-vnc)
8+
9+
## Choose the Right Solution
10+
11+
The recommended solution is [Use MATLAB Integration for Jupyter in a Docker Container](matlab). It supports MATLAB R2020b or later (64 bit Linux®) but it has some limitations (see [Specifications and Limitations](https://www.mathworks.com/products/matlab-online/limitations.html)).
12+
13+
If you want to use an earlier version of MATLAB, or if you need any features described as limitations in [Specifications and Limitations](https://www.mathworks.com/products/matlab-online/limitations.html) use the solution [Use MATLAB Integration for Jupyter using VNC in a Docker Container](matlab-vnc) to connect to a traditional MATLAB desktop via VNC.
14+

‎SECURITY.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Reporting Security Vulnerabilities
2+
==================================
3+
If you believe you have discovered a security vulnerability, please report it to
4+
[email protected] instead of GitHub. Please see
5+
[MathWorks Vulnerability Disclosure Policy for Security Researchers](https://www.mathworks.com/company/aboutus/policies_statements/vulnerability-disclosure-policy.html)
6+
for additional information.

‎matlab-vnc/Dockerfile

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Copyright 2020 The MathWorks, Inc.
2+
3+
# Replace "matlab:r2020b" with the Docker image that contains MATLAB
4+
# MATLAB should be installed at /usr/local/MATLAB or other changes will need
5+
# to be made to this Dockerfile
6+
FROM matlab:r2020b AS matlab-install-stage
7+
8+
FROM jupyter/base-notebook
9+
10+
USER root
11+
12+
# Copy MATLAB install from Docker image
13+
COPY --from=matlab-install-stage /usr/local/MATLAB /usr/local/MATLAB
14+
15+
# Add MATLAB to the path
16+
RUN ln -s /usr/local/MATLAB/bin/matlab /usr/local/bin/matlab
17+
18+
# Install MATLAB dependencies
19+
# Reference: https://github.com/mathworks-ref-arch/container-images/tree/master/matlab-deps
20+
RUN export DEBIAN_FRONTEND=noninteractive && apt-get update && apt-get install --no-install-recommends -y \
21+
libasound2 \
22+
libatk1.0-0 \
23+
libc6 \
24+
libcairo-gobject2 \
25+
libcairo2 \
26+
libcrypt1 \
27+
libcups2 \
28+
libdbus-1-3 \
29+
libfontconfig1 \
30+
libgdk-pixbuf2.0-0 \
31+
libgstreamer-plugins-base1.0-0 \
32+
libgstreamer1.0-0 \
33+
libgtk-3-0 \
34+
libnspr4 \
35+
libnss3 \
36+
libpam0g \
37+
libpango-1.0-0 \
38+
libpangocairo-1.0-0 \
39+
libpangoft2-1.0-0 \
40+
libpython2.7 \
41+
libpython3.8 \
42+
libselinux1 \
43+
libsm6 \
44+
libsndfile1 \
45+
libtcl8.6 \
46+
libuuid1 \
47+
libx11-6 \
48+
libx11-xcb1 \
49+
libxcb1 \
50+
libxcomposite1 \
51+
libxcursor1 \
52+
libxdamage1 \
53+
libxext6 \
54+
libxfixes3 \
55+
libxft2 \
56+
libxi6 \
57+
libxinerama1 \
58+
libxrandr2 \
59+
libxrender1 \
60+
libxt6 \
61+
libxtst6 \
62+
libxxf86vm1 \
63+
zlib1g \
64+
xkb-data \
65+
procps \
66+
ca-certificates \
67+
sudo \
68+
locales locales-all \
69+
&& apt-get clean \
70+
&& apt-get -y autoremove \
71+
&& rm -rf /var/lib/apt/lists/*
72+
73+
# Install jupyter-matlab-vnc dependencies
74+
RUN export DEBIAN_FRONTEND=noninteractive \
75+
&& apt-get -y update \
76+
&& apt-get install -y \
77+
dbus-x11 \
78+
firefox \
79+
xfce4 \
80+
xfce4-panel \
81+
xfce4-session \
82+
xfce4-settings \
83+
xorg \
84+
xubuntu-icon-theme \
85+
curl \
86+
&& apt-get clean \
87+
&& apt-get -y autoremove \
88+
&& rm -rf /var/lib/apt/lists/*
89+
90+
# Install tigervnc to /usr/local
91+
RUN curl -sSfL 'https://bintray.com/tigervnc/stable/download_file?file_path=tigervnc-1.10.1.x86_64.tar.gz' \
92+
| tar -zxf - -C /usr/local --strip=2
93+
94+
# noVNC provides VNC over browser capability
95+
# Set default install location for noVNC
96+
ARG NOVNC_PATH=/opt/noVNC
97+
98+
# Get noVNC
99+
RUN mkdir -p ${NOVNC_PATH} \
100+
&& curl -sSfL 'https://github.com/novnc/noVNC/archive/v1.2.0.tar.gz' \
101+
| tar -zxf - -C ${NOVNC_PATH} --strip=1 \
102+
&& chown -R ${NB_USER}:users ${NOVNC_PATH}
103+
104+
# Change user to jovyan from root as we do not want any changes to be made as root in the container
105+
USER $NB_USER
106+
107+
# Get websockify
108+
RUN conda install -y -q websockify=0.9.0
109+
110+
# Set environment variable for python package jupyter-matlab-vnc-proxy
111+
ENV NOVNC_PATH=${NOVNC_PATH}
112+
# Pip install the integration
113+
RUN python -m pip install https://github.com/mathworks/jupyter-matlab-vnc-proxy/archive/0.1.0.tar.gz
114+
115+
# Ensure jupyter-server-proxy JupyterLab extension is installed
116+
RUN jupyter labextension install @jupyterlab/server-proxy
117+
118+
# Move MATLAB resource files to the expected locations
119+
RUN export RESOURCES_LOC=$(python -c "import jupyter_matlab_vnc_proxy as pkg; print(pkg.__path__[0])")/resources \
120+
&& mkdir -p ${HOME}/.local/share/applications ${HOME}/Desktop ${HOME}/.local/share/ ${HOME}/.icons \
121+
&& cp ${RESOURCES_LOC}/MATLAB.desktop ${HOME}/Desktop/ \
122+
&& cp ${RESOURCES_LOC}/MATLAB.desktop ${HOME}/.local/share/applications\
123+
&& ln -s ${RESOURCES_LOC}/matlab_icon.png ${HOME}/.icons/matlab_icon.png \
124+
&& cp ${RESOURCES_LOC}/matlab_launcher.py ${HOME}/.local/share/ \
125+
&& cp ${RESOURCES_LOC}/mw_lite.html ${NOVNC_PATH}
126+
127+
# Fixes occasional failure to start VNC desktop, which requires a reloading of the webpage to fix.
128+
RUN touch ${HOME}/.Xauthority
129+
130+
# Uncomment and set the port and hostname to configure a network license manager for all users
131+
# ENV MLM_LICENSE_FILE port@hostname

‎matlab-vnc/Dockerfile.mounted

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Copyright 2020 The MathWorks, Inc.
2+
3+
FROM jupyter/base-notebook
4+
5+
USER root
6+
7+
# Add MATLAB to the path
8+
RUN ln -s /usr/local/MATLAB/bin/matlab /usr/local/bin/matlab
9+
10+
# Install MATLAB dependencies
11+
# Reference: https://github.com/mathworks-ref-arch/container-images/tree/master/matlab-deps
12+
RUN export DEBIAN_FRONTEND=noninteractive && apt-get update && apt-get install --no-install-recommends -y \
13+
libasound2 \
14+
libatk1.0-0 \
15+
libc6 \
16+
libcairo-gobject2 \
17+
libcairo2 \
18+
libcrypt1 \
19+
libcups2 \
20+
libdbus-1-3 \
21+
libfontconfig1 \
22+
libgdk-pixbuf2.0-0 \
23+
libgstreamer-plugins-base1.0-0 \
24+
libgstreamer1.0-0 \
25+
libgtk-3-0 \
26+
libnspr4 \
27+
libnss3 \
28+
libpam0g \
29+
libpango-1.0-0 \
30+
libpangocairo-1.0-0 \
31+
libpangoft2-1.0-0 \
32+
libpython2.7 \
33+
libpython3.8 \
34+
libselinux1 \
35+
libsm6 \
36+
libsndfile1 \
37+
libtcl8.6 \
38+
libuuid1 \
39+
libx11-6 \
40+
libx11-xcb1 \
41+
libxcb1 \
42+
libxcomposite1 \
43+
libxcursor1 \
44+
libxdamage1 \
45+
libxext6 \
46+
libxfixes3 \
47+
libxft2 \
48+
libxi6 \
49+
libxinerama1 \
50+
libxrandr2 \
51+
libxrender1 \
52+
libxt6 \
53+
libxtst6 \
54+
libxxf86vm1 \
55+
zlib1g \
56+
xkb-data \
57+
procps \
58+
ca-certificates \
59+
sudo \
60+
locales locales-all \
61+
&& apt-get clean \
62+
&& apt-get -y autoremove \
63+
&& rm -rf /var/lib/apt/lists/*
64+
65+
# Install jupyter-matlab-vnc dependencies
66+
RUN export DEBIAN_FRONTEND=noninteractive \
67+
&& apt-get -y update \
68+
&& apt-get install -y \
69+
dbus-x11 \
70+
firefox \
71+
xfce4 \
72+
xfce4-panel \
73+
xfce4-session \
74+
xfce4-settings \
75+
xorg \
76+
xubuntu-icon-theme \
77+
curl \
78+
&& apt-get clean \
79+
&& apt-get -y autoremove \
80+
&& rm -rf /var/lib/apt/lists/*
81+
82+
# Install tigervnc to /usr/local
83+
RUN curl -sSfL 'https://bintray.com/tigervnc/stable/download_file?file_path=tigervnc-1.10.1.x86_64.tar.gz' \
84+
| tar -zxf - -C /usr/local --strip=2
85+
86+
# noVNC provides VNC over browser capability
87+
# Set default install location for noVNC
88+
ARG NOVNC_PATH=/opt/noVNC
89+
90+
# Get noVNC
91+
RUN mkdir -p ${NOVNC_PATH} \
92+
&& curl -sSfL 'https://github.com/novnc/noVNC/archive/v1.2.0.tar.gz' \
93+
| tar -zxf - -C ${NOVNC_PATH} --strip=1 \
94+
&& chown -R ${NB_USER}:users ${NOVNC_PATH}
95+
96+
# Change user to jovyan from root as we do not want any changes to be made as root in the container
97+
USER $NB_USER
98+
99+
# Get websockify
100+
RUN conda install -y -q websockify=0.9.0
101+
102+
# Set environment variable for python package jupyter-matlab-vnc-proxy
103+
ENV NOVNC_PATH=${NOVNC_PATH}
104+
# Pip install the integration
105+
RUN python -m pip install https://github.com/mathworks/jupyter-matlab-vnc-proxy/archive/0.1.0.tar.gz
106+
107+
# Ensure jupyter-server-proxy JupyterLab extension is installed
108+
RUN jupyter labextension install @jupyterlab/server-proxy
109+
110+
# Move MATLAB resource files to the expected locations
111+
RUN export RESOURCES_LOC=$(python -c "import jupyter_matlab_vnc_proxy as pkg; print(pkg.__path__[0])")/resources \
112+
&& mkdir -p ${HOME}/.local/share/applications ${HOME}/Desktop ${HOME}/.local/share/ ${HOME}/.icons \
113+
&& cp ${RESOURCES_LOC}/MATLAB.desktop ${HOME}/Desktop/ \
114+
&& cp ${RESOURCES_LOC}/MATLAB.desktop ${HOME}/.local/share/applications\
115+
&& ln -s ${RESOURCES_LOC}/matlab_icon.png ${HOME}/.icons/matlab_icon.png \
116+
&& cp ${RESOURCES_LOC}/matlab_launcher.py ${HOME}/.local/share/ \
117+
&& cp ${RESOURCES_LOC}/mw_lite.html ${NOVNC_PATH}
118+
119+
# Fixes occasional failure to start VNC desktop, which requires a reloading of the webpage to fix.
120+
RUN touch ${HOME}/.Xauthority
121+
122+
# Uncomment and set the port and hostname to configure a network license manager for all users
123+
# ENV MLM_LICENSE_FILE port@hostname

‎matlab-vnc/MATLAB_mounted.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Provide MATLAB as a Volume or Bind Mount
2+
3+
To provide a MATLAB installation to the container via a volume or bind mount, instead of installing MATLAB inside the image, follow the instructions below.
4+
5+
### Build the Docker Image
6+
7+
Build a Docker image called `matlab-vnc-notebook-nomatlab`, using the file `Dockerfile.mounted`:
8+
9+
```bash
10+
docker build -f Dockerfile.mounted -t matlab-vnc-notebook-nomatlab .
11+
```
12+
13+
### Start the Docker Container
14+
15+
Execute the command below to start a Docker container, bind mount the directory `/usr/local/MATLAB/R2020a` (which must contain a MATLAB R2020b or later 64 bit Linux installation) into the directory `/usr/local/MATLAB` inside the container, and bind port 8888 on the host to port 8888 of the container (by default, Jupyter's app-server runs on port 8888 inside the container):
16+
17+
```bash
18+
docker run -it -v /usr/local/MATLAB/R2020a:/usr/local/MATLAB:ro -p 8888:8888 matlab-vnc-notebook-nomatlab
19+
```
20+
21+
Access the Jupyter Notebook by following one of the URLs displayed in the output of the ```docker run``` command.
22+
For instructions about how to use the integration, see [MATLAB Integration for Jupyter using VNC](https://github.com/mathworks/jupyter-matlab-vnc-proxy).

‎matlab-vnc/README.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Use MATLAB Integration for Jupyter using VNC in a Docker Container
2+
3+
The `Dockerfile` in this repository builds a Jupyter® Docker® image which contains the `jupyter-matlab-vnc-proxy` package.
4+
This package allows you to connect to a Linux® desktop with MATLAB® installed from your Jupyter environment.
5+
6+
If you want to install the MATLAB Integration for Jupyter using VNC without using Docker, use the installation instructions in the repository
7+
[MATLAB Integration for Jupyter using VNC](https://github.com/mathworks/jupyter-matlab-vnc-proxy) instead.
8+
9+
If you have access to MATLAB R2020b or later, we recommend using the alternative [Use MATLAB Integration for Jupyter in a Docker Container](https://github.com/mathworks-ref-arch/matlab-integration-for-jupyter/tree/main/matlab).
10+
This alternative comes with some limitations (see [Specifications and Limitations](https://www.mathworks.com/products/matlab-online/limitations.html)) but it enables you to open a MATLAB desktop in a web browser tab, directly from your Jupyter environment.
11+
12+
## Requirements
13+
14+
Before starting, make sure you have [Docker](https://docs.docker.com/get-docker/) installed on your system.
15+
16+
## Instructions
17+
18+
The `Dockerfile` in this repository builds upon the base image `jupyter/base-notebook`. Optionally, you can customize the `Dockerfile` to build upon any alternative Jupyter Docker base image.
19+
20+
To build the Docker image, follow these steps:
21+
22+
1. Select a base container image with a MATLAB R2020b or later (64 bit Linux) installation. If you need to create one, follow the steps at [Create a MATLAB Container Image](https://github.com/mathworks-ref-arch/matlab-dockerfile).
23+
24+
2. Open the `Dockerfile`, replace the name `matlab` with the name of the MATLAB image from step 1:
25+
26+
```
27+
FROM matlab AS matlab-install-stage
28+
```
29+
30+
3. If MATLAB is not installed at the location `/usr/local/MATLAB` in the image built in step 1, edit the following line to point to you MATLAB installation:
31+
32+
```
33+
COPY --from=matlab-install-stage /usr/local/MATLAB /usr/local/MATLAB
34+
```
35+
36+
For example, if MATLAB is installed at the location `/opt/matlab/R2020a` change the line above to:
37+
38+
```
39+
COPY --from=matlab-install-stage /opt/matlab/R2020a /usr/local/MATLAB
40+
```
41+
42+
4. Optionally, to preconfigure a network license manager, open the `Dockerfile`, uncomment the line below, and replace `port@hostname` with the licence server address:
43+
44+
```
45+
# ENV MLM_LICENSE_FILE port@hostname
46+
```
47+
48+
5. Build a Docker image labelled `matlab-vnc-notebook`, using the file `Dockerfile`:
49+
50+
```bash
51+
docker build -t matlab-vnc-notebook .
52+
```
53+
54+
6. Start a Docker container, and
55+
forward the default Jupyter web-app port (8888) to the host machine:
56+
57+
```bash
58+
docker run -it -p 8888:8888 matlab-vnc-notebook
59+
```
60+
61+
Access the Jupyter Notebook by following one of the URLs displayed in the output of the ```docker run``` command.
62+
For instructions about how to use the integration, see [MATLAB Integration for Jupyter using VNC](https://github.com/mathworks/jupyter-matlab-vnc-proxy).
63+
64+
#### Advanced
65+
66+
Installing MATLAB into the Docker image can make the image very large (greater than 10GB) depending on the MATLAB toolboxes installed.
67+
To make the image smaller, you can give the Docker container access to a MATLAB installation using a volume or bind mount. For more details see [Provide MATLAB as a Volume or Bind Mount](/matlab-vnc/MATLAB_mounted.md).
68+
69+
## Feedback
70+
71+
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]`.
72+
73+

0 commit comments

Comments
 (0)