Package MATLAB Standalone Applications into Docker Images

Supported Platform: Linux^® only.

This example shows how to package a MATLAB^® standalone application into a Docker^® image.

This option is best for developers who want to distribute an application in a standardized format with all dependencies included, or to run batch jobs in an orchestrator. To create a microservice Docker image that provides an HTTP/HTTPS endpoint, see Create Microservice Docker Image (MATLAB Compiler SDK).

Prerequisites

1. Verify that you have Docker installed on your Linux machine by typing docker in the terminal. If you do not have Docker installed, you can follow the instructions on the Docker website to install and set up Docker.

   https://docs.docker.com/engine/install/

2. Test your Docker installation by typing the following at the system terminal:

   docker run hello-world

   If your Docker installation is working correctly, you see the following message:

   Hello from Docker!
   This message shows that your installation appears to be working correctly.

3. Verify that MATLAB Runtime installer is available on your machine. You can verify its existence by executing the compiler.runtime.download function at the MATLAB command prompt. If there is an existing installer on the machine, the function returns its location. Otherwise, it downloads the MATLAB Runtime installer matching the version and update level of MATLAB from where the command is executed.

   If the computer you are using is not connected to the Internet, you must download the MATLAB Runtime installer from a computer that is connected to the Internet. After downloading the MATLAB Runtime installer, you need to transfer the installer to the offline computer. You can download the installer from the MathWorks website.

   https://www.mathworks.com/products/compiler/matlab-runtime.html

Create Function in MATLAB

Write a MATLAB function called mymagic and save it as mymagic.m.

function mymagic(x)
y = magic(x);
disp(y)

Test the function at the MATLAB command prompt.

mymagic(5)

    17    24     1     8    15
    23     5     7    14    16
     4     6    13    20    22
    10    12    19    21     3
    11    18    25     2     9

Create Standalone Application

Package the mymagic function into a standalone application using the compiler.build.standaloneApplication function.

res = compiler.build.standaloneApplication('mymagic.m','TreatInputsAsNumeric',true)

res = 
  Results with properties:

    BuildType: 'standaloneApplication'
        Files: {3×1 cell}
      Options: [1×1 compiler.build.StandaloneApplicationOptions]

The Results object res returned at the MATLAB command prompt contains information about the build.

Once the build is complete, the function creates a folder named mymagicstandaloneApplication in your current directory to store the standalone application.

Package Standalone Application into Docker Image

Create DockerOptions Object

Prior to creating a Docker image, create a DockerOptions object using the compiler.package.DockerOptions function and pass the Results object res and an image name mymagic-standalone-app as input arguments. The compiler.package.DockerOptions function lets you customize Docker image packaging.

opts = compiler.package.DockerOptions(res,'ImageName','mymagic-standalone-app')

opts = 
  DockerOptions with properties:

                EntryPoint: 'mymagic'
    AdditionalInstructions: {}
        AdditionalPackages: {}
        ExecuteDockerBuild: on
                 ImageName: 'mymagic-standalone-app'
             DockerContext: './mymagic-standalone-appdocker'

Create Docker Image

Create a Docker image using the compiler.package.docker function and pass the Results object res and the DockerOptions object opts as input arguments.

compiler.package.docker(res,'Options',opts)

Generating Runtime Image
Cleaning MATLAB Runtime installer location. It may take several minutes...
Copying MATLAB Runtime installer. It may take several minutes...
...
...
...
Successfully built 6501fa2bc057
Successfully tagged mymagic-standalone-app:latest

DOCKER CONTEXT LOCATION:

/home/user/MATLAB/work/mymagic-standalone-appdocker

SAMPLE DOCKER RUN COMMAND:

docker run --rm -e "DISPLAY=:0" -v /tmp/.X11-unix:/tmp/.X11-unix mymagic-standalone-app

Once packaging is complete, the function creates a folder named mymagic-standalone-appdocker in your current directory. This folder is the Docker context and contains the Dockerfile. The compiler.package.docker function also returns the location of the Docker context and a sample Docker run command. You can use the sample Docker run command to test whether your image executes correctly. If the application requires input arguments, append them to the sample command.

During the packaging process, the necessary bits for MATLAB Runtime are packaged as a parent Docker image and the standalone application is packaged as a child Docker image.

Test Docker Image

Open a Linux terminal and navigate to the Docker context folder. Verify that the mymagic-standalone-app Docker image is listed in your list of Docker images.

$ docker images

REPOSITORY                                      TAG           IMAGE ID            CREATED             SIZE
mymagic-standalone-app                          latest        6501fa2bc057        23 seconds ago      1.03GB
matlabruntime/r2024b/update0/4000000000000000   latest        c6eb5ba4ae69        24 hours ago        1.03GB

After verifying that the mymagic-standalone-app Docker image is listed in your list of Docker images, execute the sample run command with the input argument 5:

$ docker run --rm -e "DISPLAY=:0" -v /tmp/.X11-unix:/tmp/.X11-unix mymagic-standalone-app 5

No protocol specified

out =

    17    24     1     8    15
    23     5     7    14    16
     4     6    13    20    22
    10    12    19    21     3
    11    18    25     2     9

The standalone application is packaged and can now be run as a Docker image.

Note

When running applications that generate plots or graphics, execute the xhost program with the + option prior to running your Docker image.

xhost +

The xhost program controls access to the X display server, thereby enabling plots and graphics to be displayed. The + option indicates that everyone has access to the X display server. If you run the xhost program with the + option prior to running applications that do not generate plots or graphics, the message No protocol specified is no longer displayed.

Share Docker Image

You can share your Docker image in various ways.

• Push your image to the Docker's central registry DockerHub, or to your private registry. This is the most common workflow.

• Save your image as a tar archive and share it with others. This workflow is suitable for immediate testing.

For details about pushing your image to Docker's central registry or your private registry, consult the Docker documentation.

Save Docker Image as Tar Archive

To save your Docker image as a tar archive, open a Linux terminal, navigate to the Docker context folder, and type the following.

$ docker save mymagic-standalone-app -o mymagic-standalone-app.tar

A file named mymagic-standalone-app.tar is created in your current folder. Set the appropriate permissions using chmod prior to sharing the tarball with other users.

Load Docker Image from Tar Archive

Load the image contained in the tarball on the end-user's machine and then run it.

$ docker load --input mymagic-standalone-app.tar

Verify that the image is loaded.

$ docker images

Run Docker Image

$ xhost + $ docker run --rm -e "DISPLAY=:0" -v /tmp/.X11-unix:/tmp/.X11-unix mymagic-standalone-app 5