Main Content

compiler.package.microserviceDockerImage

Create a microservice Docker image using files generated by MATLAB Compiler SDK

Since R2022a

collapse all in page

Syntax

compiler.package.microserviceDockerImage(results)
compiler.package.microserviceDockerImage(results,Name,Value)
compiler.package.microserviceDockerImage(results,'Options',opts)
compiler.package.microserviceDockerImage(files,filepath,'ImageName',imageName)
compiler.package.microserviceDockerImage(files,filepath,'ImageName',imageName,Name,Value)
compiler.package.microserviceDockerImage(files,filepath,'Options',opts)

Description

compiler.package.microserviceDockerImage(results) creates a Docker® image for files generated by the MATLAB® Compiler SDK™ using the compiler.build.Results object results. The results object is created by the compiler.build.productionServerArchive function.

example

compiler.package.microserviceDockerImage(results,Name,Value) creates a Docker image using the compiler.build.Results object results and additional options specified as one or more name-value arguments. Options include the build folder, entry point command, and image name.

example

compiler.package.microserviceDockerImage(results,'Options',opts) creates a Docker image using the compiler.build.Results object results and additional options specified by a MicroserviceDockerImageOptions object opts. If you use a MicroserviceDockerImageOptions object, you cannot specify any other options using name-value arguments.

example

compiler.package.microserviceDockerImage(files,filepath,'ImageName',imageName) creates a Docker image using files that are generated by MATLAB Compiler SDK. The Docker image name is specified by imageName.

example

compiler.package.microserviceDockerImage(files,filepath,'ImageName',imageName,Name,Value) creates a Docker image using files that are generated by MATLAB Compiler SDK. Additional options are specified as one or more name-value arguments.

example

compiler.package.microserviceDockerImage(files,filepath,'Options',opts) creates a Docker image using files that are generated by MATLAB Compiler SDK and additional options specified by a MicroserviceDockerImageOptions object opts. If you use a MicroserviceDockerImageOptions object, you cannot specify any other options using name-value arguments.

example

Examples

collapse all

Create a microservice Docker image from a production server archive.

Install and configure Docker on your system. For details, see the prerequisites section of Create Microservice Docker Image.

Create a production server archive using magicsquare.m and save the build results to a compiler.build.Results object.

appFile = fullfile(matlabroot,'extern','examples','compiler','magicsquare.m');
buildResults = compiler.build.productionServerArchive(appFile);

Pass the Results object as an input to the compiler.package.microserviceDockerImage function to build the Docker image.

compiler.package.microserviceDockerImage(buildResults);

The function generates the following files within a folder named magicsquaremicroserviceDockerImage in your current working directory:

  • applicationFilesForMATLABCompiler/magicsquare.ctf — Deployable archive file.

  • Dockerfile — Docker file that specifies Docker run time options.

  • GettingStarted.txt — Text file that contains deployment information.

To deploy the image to Docker using port 9900 on the host machine, run the following command in a system terminal:

docker run --rm -p 9900:9910 magicsquare

Customize a microservice image using name-value arguments on a Linux® system to specify the image name and build directory.

Create a production server archive using magicsquare.m and save the build results to a compiler.build.Results object.

appFile = fullfile(matlabroot,'extern','examples','compiler','magicsquare.m');
buildResults = compiler.build.productionServerArchive(appFile);

Call the compiler.package.microserviceDockerImage function using the Results object. Use name-value pair arguments to specify the image name and build folder, and disable the call to build the Docker image.

compiler.package.microserviceDockerImage(buildResults,...
'ImageName','mymagicapp',...
'DockerContext','/home/mluser/Documents/MATLAB/docker',...
'ExecuteDockerBuild','Off');

This syntax populates the context folder with the Docker files.

After you have examined the generated files, use the command docker build to build the Docker image. For details, refer to the Docker documentation.

Customize a Docker image using a MicroserviceDockerImageOptions object.

Write a function named helloworld.m using the following code.

disp('Hello world!');

Create a production server archive using helloworld.m and save the build results to a compiler.build.Results object.

buildResults = compiler.build.productionServerArchive('helloworld.m');

Create a MicroserviceDockerImageOptions object to specify additional build options.

opts = compiler.package.MicroserviceDockerImageOptions(buildResults,...
'DockerContext','hellodocker')
opts = 

  MicroserviceDockerImageOptions with properties:

                 RoutesFile: ''
                 ImageName: 'helloworld-microservice'
              RuntimeImage: ''
    AdditionalInstructions: {}
        AdditionalPackages: {}
        ExecuteDockerBuild: on
             ContainerUser: 'appuser'
             DockerContext: './hellodocker'
            VerbosityLevel: 'verbose'

Pass the MicroserviceDockerImageOptions and Results objects as inputs to the compiler.package.microserviceDockerImage function to build the Docker image.

compiler.package.microserviceDockerImage(buildResults,'Options',opts);

Create a Docker image using files generated by MATLAB Compiler SDK and specify the image name.

Build a production server archive using the mcc command.

mcc -W CTF:myapp -U magicsquare.m

Build the Docker image by passing the generated files to the compiler.package.microserviceDockerImage function.

compiler.package.microserviceDockerImage('myapp.ctf',...
'requiredMCRProducts.txt','ImageName','microapp');

Customize a Docker image using files generated by MATLAB Compiler SDK and a MicroserviceDockerImageOptions object.

Create a production server archive using helloworld.m and save the build results to a compiler.build.Results object.

buildResults = compiler.build.productionServerArchive('helloworld.m');

Create a MicroserviceDockerImageOptions object to specify additional build options, such as the build folder.

opts = compiler.package.MicroserviceDockerImageOptions(buildResults,...    
'DockerContext','DockerImages')

You can modify property values of an existing MicroserviceDockerImageOptions object using dot notation. For example, disable the call to build the Docker image.

opts.ExecuteDockerBuild = 'Off';

Populate the DockerContext folder with the Docker files by passing the files and options object to the compiler.package.microserviceDockerImage function.

cd helloworldproductionServerArchive

compiler.package.microserviceDockerImage('helloworld.ctf',...
'requiredMCRProducts.txt','Options',opts);

Input Arguments

collapse all

Build results created by the compiler.build.productionServerArchive function, specified as a compiler.build.Results object.

Files and folders for installation, specified as a character vector, string scalar, string array, or cell array of strings. Exactly one of these files must be a code archive (CTF file) generated by MATLAB Compiler SDK. The list can also include any additional files and folders required by the service to run. You can package files generated by MATLAB Compiler SDK in a particular release using the compiler.package.microserviceDockerImage function of the same release.

Example: ['helloworld.ctf','myDockerFiles/']

Data Types: char | string | cell

Path to the requiredMCRProducts.txt file, specified as a character vector or string scalar. This file is generated by MATLAB Compiler SDK. The path can be relative to the current working directory or absolute.

Example: '/home/mluser/Documents/MATLAB/magicsquare/requiredMCRProducts.txt'

Data Types: char | string

Name of the Docker image. It must comply with Docker naming rules.

Example: 'hello-world'

Data Types: char | string

Microservice Docker options, specified as a MicroserviceDockerImageOptions object.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'ExecuteDockerBuild','on'

Since R2022b

Additional commands to pass to the Docker image, specified as a character vector, a string scalar, or a cell array of character vectors. Commands are added to the Dockerfile and execute during image generation.

For information on valid Dockerfile commands, see https://docs.docker.com/engine/reference/builder/.

Example: 'AdditionalInstructions',{'RUN mkdir /myvol','RUN echo "hello world" > /myvol/greeting','VOLUME /myvol'}

Data Types: char | string

Since R2022b

Additional Ubuntu® 20.04 packages to install into the Docker image, specified as a character vector, a string scalar, or a cell array of character vectors.

Example: 'AdditionalPackages','syslog-ng'

Data Types: char | string

Since R2023b

Name of the Linux user the Docker container will run as, specified as a character vector or a string scalar. The argument must comply with system user naming standards. If the specified user does not exist at the time of creation, a new user will be created with no permissions. If this property is not set, the container will run as the user appuser by default, or the user specified in the FROM command in the Dockerfile.

Example: 'ContainerUser','root'

Data Types: char | string

Path to the build folder where the Docker image is built, specified as a character vector or a string scalar. The path can be relative to the current working directory or absolute.

If no path is specified, the function creates a build folder named ImageNamedocker in the current working directory.

Example: 'DockerContext','/home/mluser/Documents/MATLAB/docker/magicsquaredocker'

Data Types: char | string

Flag to build the Docker image, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

  • If you set this property to 'on', then the function will build the Docker image.

  • If you set this property to 'off', then the function will populate the DockerContext folder without calling 'docker build'.

Example: 'ExecuteDockerBuild','Off'

Data Types: logical

Name of the Docker image, specified as a character vector or a string scalar. The name must comply with Docker naming rules. Docker repository names must be lowercase. If the main executable or archive file is named using uppercase letters, then the uppercase letters are replaced with lowercase letters in the Docker image name.

Example: 'ImageName','magicsquare'

Data Types: char | string

Since R2023a

Path to a JSON file that specifies custom URL routes on the server, specified as a character vector or a string scalar.

Example: 'RoutesFile','routes.json'

Data Types: char | string

Since R2023b

Name of the MATLAB Runtime image, specified as a character vector or a string scalar. You can use the compiler.runtime.createDockerImage function to create a custom MATLAB Runtime image that can run multiple applications. If not specified, MATLAB Compiler™ generates a selective MATLAB Runtime image that can only run the packaged application.

Example: 'RuntimeImage','mcrimage'

Data Types: char | string

Since R2023b

Output verbosity level, specified as one of the following options:

  • 'verbose' (default) — Display all screen output, including Docker output that occurs from the commands 'docker pull' and 'docker build'.

  • 'concise' — Display progress information without Docker output

  • 'none' — Do not display output.

Example: 'VerbosityLevel','concise'

Data Types: char | string

Limitations

  • In R2022a, this function is only supported on Linux operating systems.

Version History

Introduced in R2022a

See Also

| | |

Topics