Using Matlab through Docker

Instead of installing Matlab on your local machine, a better option is to run Matlab within a Docker container. This ensures that you are always starting with a clean environment, and allows you to very easily share your project in a reproducible manner.

The Basics

Running Matlab inside of Docker can be done with a single command:

docker run -it -p 8888:8888 --shm-size=512M mathworks/matlab:r2022a -browser

Breaking the command down:

• run || starts a new docker container from an image
• -it || interactive flag, means that the container’s execution will show up in the bash session you start the container from
• -p 8888:8888 || port mapping, maps port 8888 inside the container to the same port on the computer you’re running the container on
• mathworks/matlaScreenshot from 2022-08-24 12-38-21b:r2022a || the name/tag of the docker image to run
• -browser || tells Matlab to run an interactive browser session for the GUI, hosted on http://localhost:8888/index.html

Once you run the above command, you’ll see the following:

Your computer is now downloading the Matlab Docker image for r2022a. Once the download is finished, the container will start, and you’ll see the following:

If you type the web address into your browser, you’ll then see:

Log in to your CWRU Matlab account. Once you finish logging in, you should see a Matlab interface within your browser:

You are now running Matlab inside a clean Docker container. Note that anything you make/write inside this container is ONLY saved to the container (for now…. we’ll fix that later in this guide). But feel free to try using the Dockerized Matlab appliance now!

Changing Docker Images

The Docker image we used above (mathworks/matlab:r2022a) is a basic, clean installation of Matlab. However, for a lot of the work done in lab, we likely need some other toolboxes. Instead of using this as the base image, we can instead use Mathworks’ “Deep Learning” docker image as a base.

Doing so is as easy as changing the image in the run command to:

docker run -it -p 8888:8888 --shm-size=512M mathworks/matlab-deep-learning:r2022a -browser

Your computer will begin downloading the additional toolkit layers for the Docker image. Once it’s done, you’ll be all set to use the larger, more capable image instead.

Using GPUs

Now that we’ve changed to the Deep Learning image, we may also want to add support for the GPUs installed in many of our computers. Doing so is as easy as adding a flag to the run command:

docker run --gpus all -it -p 8888:8888 --shm-size=512M mathworks/matlab-deep-learning:r2022a -browser

This will forward the GPUs installed in your machine to the Docker container for use by Matlab.

Mounting Existing Code/Directories into Container

Most likely, you already have code that you’d like to open in Matlab. In order to do so, we need to mount the folder containing that code as a volume inside the Matlab container. In the below example, I’m mounting a directory called “code” that’s inside my user folder on the host machine to the default MATLAB directory inside the container:

docker run \
-v /home/andrew/code:/home/matlab/Documents/MATLAB/code \
--gpus all -it -p 8888:8888 --shm-size=512M mathworks/matlab-deep-learning:r2022a -browser

As you can see, once Matlab starts up, the “code” folder and it’s contents from my local computer are now available within the running Matlab instance:

Just to test the functionality, try making a file inside the browser Matlab instance called “newFile.m”. You’ll see it show up in the local filesystem too:

Now, files you make will persist after you close the Matlab Docker container, as long as those changes are inside of a volume you have mapped to the container during startup.

Making and Sharing a Docker Image

If you have a folder with some Matlab code inside it, this can also be used to quickly create a custom Matlab docker image that includes your code. We can do this with a very simple Dockerfile. Make a new, empty text file named “Dockerfile” in the directory above where your code lives:

Inside the Dockerfile, we’ll have three main lines:

FROM mathworks/matlab-deep-learning:r2022a
COPY code /home/matlab/Documents/MATLAB/code
CMD ["matlab"]

Breaking this down:

• FROM || Specifies the source Docker image to use as the base for your new, custom image
• COPY || Copies a folder or file from a location “code” to a location inside the new Docker image (/home/matlab/Documents/MATLAB/code)
• CMD || Specifies the command to run when the Docker container first starts – in this case, Matlab

In order to build this new Docker image, we”ll open the root directory in the terminal and enter:

docker build .

Once the process completes, you’ll see:

You now have a custom Docker image containing your code, as well as a full installation of Matlab. To make things easier to keep track of, lets tag that new image with a human-readable name using:

docker tag ac987d5b17dc matlab-tutorial

You’ll need to replace the first part of the tag command with the hash given after the build process completed (after “Successfully built” in the screenshot above). Now that our new image is tagged, and we can easily run it with:

docker run -it -p 8888:8888 --shm-size=512M matlab-tutorial -browser

Once Matlab start up, you can see that our source code is included inside the image itself:

Importantly for the sake of reproducibility, the code inside this “built” version of the Docker container/image is now “read only”, unlike when you mounted the code folder as a volume. This means that anyone, anywhere who opens the Docker image you just built can run the exact same code you ran, and can’t edit it without making a copy inside the container. This is now a runnable, shareable, immutable version of your code.

If you want to see how to publish this Docker image to a Container Registry so others can use it, see this post.

The buildable sample we just put together can be downloaded below:

Data Processing Example

Lets image that we need to process a specific dataset, at a specific file location, with an existing set of Matlab code. In this case, we’ll start with some simple code that loads an image from file, displays it, inverts the colors, and displays the result as well.

We’ll start our development process by starting a docker container that maps a “code” location and a “data” location into the Matlab instance:

docker run \
-v /home/andrew/example/code:/home/matlab/Documents/MATLAB/code \
-v /home/andrew/example/data:/home/matlab/Documents/MATLAB/data \
-it -p 8888:8888 --shm-size=512M mathworks/matlab-deep-learning:r2022a -browser

As you can see, both of the folders, as well as their contents, are now mapped into the running Matlab container:

Now, we can start developing our data processing code. Anything we save while the code and data locations are mapped will be saved to the host machine as well. Here’s our basic code, and the results:

Now, lets build a docker container based on this project. We’ll use the same Dockerfile we wrote above:

FROM mathworks/matlab-deep-learning:r2022a
COPY code /home/matlab/Documents/MATLAB/code
CMD ["matlab"]

Notice that we’re not copying the “data” directory over to the Docker image, since there’s no reason to copy our datasets into the shared image. We’ll add this Dockerfile to the parent directory and run a build, then tag the result as matlab-image-example:

Now that the container is built, lets test it using the same dataset we used before. Since the data isn’t inside the container image (as we mentioned above), we’ll need to mount the data directory into the right location that we used in our code above:

docker run -v /home/andrew/example/data:/home/matlab/Documents/MATLAB/data -it -p 8888:8888 --shm-size=512M matlab-image-example -browser

As we can see, the Matlab instance that opened has the “code” in the proper code directory, as well as the same dataset inside of the data directory. However, the code is now “read-only”, as we can see from it being greyed out:

We now have a working data processing Matlab Docker container! Lets try testing with a different data set of 15 images that I downloaded from the web. Instead of moving this to the “data” folder we used for development, I can just start the Docker container directly, pointing to the folder in my downloads:

docker run -v /home/andrew/Downloads/flowers:/home/matlab/Documents/MATLAB/data -it -p 8888:8888 --shm-size=512M matlab-image-example -browser

Once Matlab opens, we’ll see that the new flowers dataset is mapped correctly into the data directory. Running the code now outputs 15 figures, one for each flower:

The source folders for the above example are included below:

You can continue extending this example with more mount folders (for example, a folder for results?), by allowing you to run the commands necessary from a batch terminal, and more. Additional documentation is available from Mathworks directly, for some of these more advanced use cases.