Main Content

compiler.package.MicroserviceDockerImageOptions

Create a microservice Docker options object

Since R2022a

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

Description

example

opts = compiler.package.MicroserviceDockerImageOptions(results) creates a MicroserviceDockerImageOptions object opts using the compiler.build.Results object results. The Results object is created by the compiler.build.productionServerArchive function. Pass the MicroserviceDockerImageOptions object as an input to the compiler.package.docker function to specify build options.

example

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

example

opts = compiler.package.MicroserviceDockerImageOptions('ImageName',imageName) creates a default MicroserviceDockerImageOptions object with the image name specified by imageName.

example

opts = compiler.package.MicroserviceDockerImageOptions('ImageName',imageName,Name,Value) creates a generic MicroserviceDockerImageOptions object with the image name specified by imageName and additional options specified as one or more pairs of name-value arguments.

Examples

collapse all

Create a MicroserviceDockerImageOptions object using the build results from a production server archive.

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);

Create a MicroserviceDockerImageOptions object using the build results from the compiler.build.productionServerArchive function.

opts = compiler.package.MicroserviceDockerImageOptions(buildResults);

You can modify property values of an existing MicroserviceDockerImageOptions object using dot notation. For example, set the build folder.

opts.DockerContext = 'myDockerFiles';

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

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

Create a MicroserviceDockerImageOptions object using build results from a production server archive and customize it using name-value arguments.

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);

Create a MicroserviceDockerImageOptions object using the build results from the compiler.build.productionServerArchive function. Use name-value arguments to specify the image name and build folder.

opts = compiler.package.MicroserviceDockerImageOptions(buildResults,...
'DockerContext','Docker/MagicSquareMicroservice',...
'ImageName','micromagic')
opts = 

  MicroserviceDockerImageOptions with properties:

                RoutesFile: ''
                 ImageName: 'micromagic'
              RuntimeImage: ''
    AdditionalInstructions: {}
        AdditionalPackages: {}
        ExecuteDockerBuild: on
             ContainerUser: 'appuser'
             DockerContext: './Docker/MagicSquareMicroservice'
            VerbosityLevel: 'verbose'

Create a generic MicroserviceDockerImageOptions object by only specifying the image name.

Create a MicroserviceDockerImageOptions object.

opts = compiler.package.MicroserviceDockerImageOptions('ImageName','helloworld')
opts = 

  MicroserviceDockerImageOptions with properties:

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

Create a MicroserviceDockerImageOptions object using the image name and customize it using name-value arguments.

Create a MicroserviceDockerImageOptions object. Use name-value arguments to specify the image name and build folder.

opts = compiler.package.MicroserviceDockerImageOptions('ImageName','myapp',...
'DockerContext','Docker/MyDockerApp')
opts = 

  MicroserviceDockerImageOptions with properties:

                RoutesFile: ''
                 ImageName: 'myapp'
              RuntimeImage: ''
    AdditionalInstructions: {}
        AdditionalPackages: {}
        ExecuteDockerBuild: on
             ContainerUser: 'appuser'
             DockerContext: './Docker/MyDockerApp'
            VerbosityLevel: 'verbose'

Input Arguments

collapse all

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

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

Example: 'hello-world'

Data Types: char | string

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

Output Arguments

collapse all

Microservice Docker image build options, returned as a MicroserviceDockerImageOptions object.

Version History

Introduced in R2022a