Main Content

compiler.package.microserviceDockerImage

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

Description

example

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.

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 hello-world.m using the following code.

disp('Hello world!');

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

buildResults = compiler.build.productionServerArchive('hello-world.m');

Create a MicroserviceDockerImageOptions object to specify additional build options.

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

  MicroserviceDockerImageOptions with properties:

    ExecuteDockerBuild: on
             ImageName: 'helloworld'
         DockerContext: 'hellodocker'

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',...
'requiredMCRProducts.txt','Options',opts);

Input Arguments

collapse all

Build results created by a compiler.build 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 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: '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'

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.

Example: 'AdditionalCommands','top'

Data Types: char | string

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

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

Limitations

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

Version History

Introduced in R2022a