search

mathworks-ref-arch / matlab-integration-for-jupyter

Create Jupyter Docker images with MATLAB integration
Other
26 stars 8 forks source link
docker dockerfile jupyterhub matlab matlab-jupyter

readme

MATLAB Integration for Jupyter Reference Architecture

To run MATLAB® in Jupyter® inside a container, use the Dockerfile in this repository. The Dockerfile builds an image with MATLAB Integration for Jupyter (GitHub), based on a jupyter/base-notebook:ubuntu-22.04 base image from Jupyter Docker Stacks (GitHub), which ships with Python 3.11.

Build Instructions

Get Sources

Access this Dockerfile either by directly downloading this repository from GitHub, or by cloning this repository and then navigating to the appropriate folder.

git clone https://github.com/mathworks-ref-arch/matlab-integration-for-jupyter.git
cd matlab-integration-for-jupyter

Build & Run Docker Container

Build the container with a name and tag of your choice.

docker build -t mifj:R2024b .

Run the container.

docker run -it -p 8888:8888 --rm mifj:R2024b

To open JupyterLab, use your browser to visit the address printed in your console of the format http://<hostname>:8888/?token=<token>. The hostname is the name of the computer running Docker, and the token is the secret token printed in the console.

For more information on running Jupyter images, see Jupyter Quick Start (Jupyter Docker Stacks).

Customize the Image

By default, the Dockerfile installs MATLAB for the latest available MATLAB release, without any additional toolboxes or products, into the /opt/matlab folder, along with the Python package jupyter-matlab-proxy, which provides the MATLAB Integration for Jupyter.

To customize your build, use the options below.

Customize MATLAB Release, MATLAB Product List, MATLAB Install Location, License Server and other Python Packages

The Dockerfile supports the following Docker build-time variables.

Argument Name Description Default value
MATLAB_RELEASE The MATLAB release you want to install. R2024b
MATLAB_PRODUCT_LIST Products to install as a space-separated list. For more information, see MPM.md. For example: MATLAB Simulink Deep_Learning_Toolbox Fixed-Point_Designer. MATLAB
MATLAB_INSTALL_LOCATION The path to install MATLAB. /opt/matlab
LICENSE_SERVER The port and hostname of the machine that is running the Network License Manager, using the port@hostname syntax. For example: 27000@MyServerName Unset
INSTALL_MATLABENGINE Set this value to install the MATLAB Engine for Python into the image. Unset
INSTALL_VNC Set this value to install the jupyter-matlab-vnc-proxy, which allows you to connect to a traditional MATLAB desktop via VNC. Unset

To customize your build, use these arguments with the docker build command. See these examples:

Build an Image for a Different Release of MATLAB

To build an image for MATLAB R2019b, run:

docker build --build-arg MATLAB_RELEASE=R2019b -t mifj:R2019b .

Build an Image with Specific Products

To build an image with MATLAB and Simulink, run:

docker build --build-arg MATLAB_PRODUCT_LIST='MATLAB Simulink' -t mifj:R2024b .

Build an Image with MATLAB Installed in a Specific Location

To build an image with MATLAB installed at /opt/matlab, use this command.

docker build --build-arg MATLAB_INSTALL_LOCATION='/opt/matlab' -t mifj:R2024b .

Build an Image Configured to Use a License Server

If you include the license server information with the docker build command, you do not have to provide it when running the container.

# Build container with the License Server.
docker build --build-arg LICENSE_SERVER=27000@MyServerName -t mifj:R2024b .

# Run the container, without providing license information.
docker run -it --rm -p 8888:8888 mifj:R2024b

Alternatively, to provide the License Server information with docker run, you can use the environment variable MLM_LICENSE_FILE:

docker run -it --rm -p 8888:8888 -e MLM_LICENSE_FILE=27000@MyServerName mifj:R2024b

For more information on using the Network License Manager, see Use the Network License Manager for more information.

Build an Image with the MATLAB Engine for Python

To build the default image along with the MATLAB Engine for Python for a given MATLAB Release, run:

docker build --build-arg INSTALL_MATLABENGINE=1 --build-arg MATLAB_RELEASE=R2024b -t mifj:R2024b .

For more information, see:

Note:

Build an Image with the MATLAB Integration for Jupyter using VNC

To build the default image along with the MATLAB Integration for Jupyter using VNC, run:

docker build --build-arg INSTALL_VNC=1 -t mifj:R2024b .

For more information, see MATLAB Integration for Jupyter using VNC(GitHub).

Installing MATLAB

There are 3 ways to include MATLAB in your container image.

  1. Install MATLAB using MATLAB Package Manager (mpm).
  2. Mount MATLAB on the Image.
  3. Bring Your Own Image (BYOI)
    • Copy MATLAB installation from another container image.

Install MATLAB using mpm

The default configuration of the Dockerfile uses mpm to install MATLAB and the specified toolboxes into the container image as described in the sections above.

Mount MATLAB on the Image

To provide a MATLAB installation to the container via volume or bind mount, instead of installing MATLAB inside the image, follow the instructions below.

The Dockerfile assumes that you want to mount MATLAB in the /opt/matlab folder. Use the Build Argument MATLAB_INSTALL_LOCATION to specify a custom location within the container where you want to mount MATLAB.

Build Image

Use the Dockerfile Build Arguments MOUNT_MATLAB and MATLAB_RELEASE with your docker build command.

docker build --build-arg MOUNT_MATLAB=1 \
             --build-arg MATLAB_RELEASE=R2024b \
             -t mifj:mounted .

The MATLAB_RELEASE argument ensures that the system dependencies required for MATLAB are installed in the container.

Note: When you are mounting MATLAB on the container at run time, you cannot install MATLAB Engine for Python at build time.

Specify Mount Location at Container Startup

If MATLAB is installed in /usr/local/MATLAB/R2024b on your local machine, you can bind mount this folder to /opt/matlab using the command shown below:

docker run -it --rm -v /usr/local/MATLAB/R2024b:/opt/matlab:ro -p 8888:8888 mifj:mounted

For more information, see Bind Mounts (Docker).

Access the Jupyter Notebook by following one of the URLs displayed in the output of the docker run command.

This option is useful when you want to minimize the size of the container as installing MATLAB and its toolboxes can make the image large (greater than 10GB), depending on the MATLAB toolboxes installed.

Bring Your Own Image

To copy an existing MATLAB installation from another container image, specify the image name with the Docker Build Arguments MATLAB_IMAGE_NAME and MATLAB_RELEASE as shown below:

# Copies MATLAB from the Dockerhub Image "mathworks/matlab:r2024b" into the image being built.
docker build --build-arg MATLAB_IMAGE_NAME=mathworks/matlab:r2024b \
             --build-arg MATLAB_RELEASE=R2024b \
             -t mifj:copied .

The MATLAB_RELEASE argument, ensures that the system dependencies required for MATLAB, are installed into the container.

Pre-Built Images

You can download several Docker images based on this Dockerfile from the GitHub Container Registry.

jupyter-matlab-notebook

These images are based on jupyter/base-notebook:ubuntu-22.04 and include:

Available Tags: R2024b, R2024a, R2023b, R2023a, R2022b

Docker Pull Command:

# Substitute the tag with your desired version of MATLAB.
docker pull ghcr.io/mathworks-ref-arch/matlab-integration-for-jupyter/jupyter-matlab-notebook:R2024b

jupyter-mounted-matlab-notebook

These images are based on jupyter/base-notebook:ubuntu-22.04 and include:

Available Tags: R2024b, R2024a, R2023b, R2023a, R2022b

Docker Pull Command:

# Substitute the tag with your desired version of MATLAB.
docker pull ghcr.io/mathworks-ref-arch/matlab-integration-for-jupyter/jupyter-mounted-matlab-notebook:R2024b

Use the correct version of the image based on the MATLAB release you are mounting on the image. For example to mount R2022b from your local machine, that is installed in /usr/local/MATLAB/R2022b, use the following docker run command:

docker run -it --rm -v /usr/local/MATLAB/R2022b:/opt/matlab:ro -p 8888:8888 ghcr.io/mathworks-ref-arch/matlab-integration-for-jupyter/jupyter-mounted-matlab-notebook:R2022b

Compatibility for Different Versions of OS or Python

To build on older versions of Ubuntu or Python, update the base image used in the Dockerfile with the tags specified in the Jupyter Docker Stacks repository.

For example, this page lists 4d70cf8da953 as the tag for an image with Python 3.10 on Ubuntu 22.04.

To build an image with this base layer, update Line 66 in the Dockerfile to FROM quay.io/jupyter/base-notebook:4d70cf8da953.

This might be useful if your workflow depends on older versions of Python. For example the MATLAB Engine for Python only supports Python 3.11 from R2023b. Installing it on MATLAB releases older than R2023b would require an older version of Python, and you can use the approach above to build an image with the desired Python version. For more information about Python compatibility for MATLAB Products, see Python Versions for MATLAB Products.

MATLAB Dependencies

To verify that the release of MATLAB you are installing is supported for your operating system, consult the MATLAB Dependencies repository. For example, R2024b is currently the only MATLAB Release which supports Ubuntu 24.04.

Support & Feedback

To submit an enhancement request or request technical support, create an Issue.

Copyright 2020-2024 The MathWorks, Inc.