compiler.package.DockerOptions

Create a Docker options object

collapse all in page

Syntax

opts = compiler.package.DockerOptions(results)
opts = compiler.package.DockerOptions(results,Name,Value)
opts = compiler.package.DockerOptions('ImageName',imageName)
opts = compiler.package.DockerOptions('ImageName',imageName,Name,Value)

Description

Caution

This function is only supported on Linux® operating systems.

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

example

opts = compiler.package.DockerOptions(results,Name,Value) creates a DockerOptions 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.DockerOptions('ImageName',imageName) creates a default DockerOptions object with the image name specified by imageName.

example

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

example

Examples

collapse all

Create a DockerOptions object using the build results from a standalone application on a Linux system.

Create a standalone application 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.standaloneApplication(appFile);

Create a DockerOptions object using the build results from the compiler.build.standaloneApplication function.

opts = compiler.package.DockerOptions(buildResults);

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

opts.DockerContext = 'myDockerFiles';

The DockerOptions and Results objects are passed as inputs to the compiler.package.docker function to build the Docker® image.

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

Create a DockerOptions object using build results from a standalone application and customize it using name-value arguments.

Create a standalone application 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.standaloneApplication(appFile);

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

opts = compiler.package.DockerOptions(buildResults,...
'DockerContext','Docker/MagicSquare',...
'ImageName','magic-square-')
opts = 

  DockerOptions with properties:

                EntryPoint: 'magicsquare'
                 ImageName: 'magic-square-'
              RuntimeImage: ''
    AdditionalInstructions: {}
        AdditionalPackages: {}
        ExecuteDockerBuild: on
             ContainerUser: 'appuser'
             DockerContext: './Docker/MagicSquare'
            VerbosityLevel: 'verbose'

Create a default DockerOptions object to specify the image name.

Create a DockerOptions object.

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

  DockerOptions with properties:

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

You can modify property values of an existing DockerOptions object using dot notation. For example, populate the DockerContext folder without calling 'docker build'.

opts.ExecuteDockerBuild = 'Off'
opts = 

  DockerOptions with properties:

                EntryPoint: ''
                 ImageName: 'helloworld'
              RuntimeImage: ''
    AdditionalInstructions: {}
        AdditionalPackages: {}
        ExecuteDockerBuild: off
             ContainerUser: 'appuser'
             DockerContext: './helloworlddocker'
            VerbosityLevel: 'verbose'

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

Create a DockerOptions object. Use name-value arguments to specify the build folder and entry point command.

opts = compiler.package.DockerOptions('ImageName','myapp',...
'DockerContext','Docker/MyDockerApp',...
'EntryPoint',"exec top -b")
opts = 

  DockerOptions with properties:

                EntryPoint: 'exec top -b'
                 ImageName: 'myapp'
              RuntimeImage: ''
    AdditionalInstructions: {}
        AdditionalPackages: {}
        ExecuteDockerBuild: on
             ContainerUser: 'appuser'
             DockerContext: './Docker/MyDockerApp'
            VerbosityLevel: 'verbose'

Input Arguments

collapse all

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

collapse all

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® 22.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

The command to be executed at image start-up, specified as a character vector or a string scalar.

Example: 'EntryPoint','exec top -b'

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 R2023b

Name of the MATLAB Runtime image, specified as a character vector or a string scalar. You can use the compiler.runtime.createDockerImage (MATLAB Compiler SDK) 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

Docker image build options, returned as a DockerOptions object.

Limitations

  • Only standalone applications can be packaged into Docker images as of R2020b.

Version History

Introduced in R2020b

See Also

| |