Build and Use Docker Image to Run Processes

This example uses:

CI Support Package for Simulink CI Support Package for Simulink

To run your tasks in a scalable and reproducible way, you can set up your build environment within a Docker^® image.

This example shows how to:

Create a custom Docker image that includes the CI Support Package for Simulink^® and other required MathWorks^® products
Extend the image with additional CI tools that support pipeline generation.
Configure build agents to support the use of a container image. The specific steps vary depending on which CI platform you choose.

Prerequisites

Before you begin, you must set up a Linux^® build agent that has Docker Engine installed. See the Docker documentation for Install Docker Engine.

Create Docker Image with CI Support Package

To run your tasks in a CI pipeline, you can create a customized Docker image that includes the CI Support Package for Simulink and other required MathWorks products. The image supports non-interactive MATLAB^® workflows in CI pipelines where interactive licensing is not possible.

Review the licensing requirements in Create a MATLAB Container Image for Non-Interactive Workflows.
Download the MATLAB Dockerfile for non-interactive workflows and save the file as non-interactive.Dockerfile.
This Dockerfile allows you to build a Docker image that installs the CI Support Package for Simulink using MATLAB Package Manager (MPM). By default, this Dockerfile sets the ENTRYPOINT to use xvfb-run, so the resulting container runs MATLAB with a virtual display. Some MATLAB code requires a display environment to run successfully. If your process does not need a virtual display, you can adjust or remove the ENTRYPOINT as needed.

Customize and build the Docker image by using the optional build arguments in the docker build command to specify your MATLAB release and the list of MathWorks products to install.

For example, you can use a PowerShell script to set your variables and build the image:

$CONTAINER_REGISTRY = "<Container_Register_Domain>"
$PADV_IMAGE = "<Custom_Docker_Image_Name>"
$PADV_IMAGE_TAG = "<Custom_Image_Tag>"
$MATLAB_RELEASE = "R2025a"
$PADV_IMAGE_NAME = "${PADV_IMAGE}:${PADV_IMAGE_TAG}"

docker buildx build -f non-interactive.Dockerfile `
  --build-arg MATLAB_RELEASE=$MATLAB_RELEASE `
  --build-arg MATLAB_PRODUCT_LIST='MATLAB Simulink Simulink_Check CI/CD_Automation_for_Simulink_Check' `
  -t $CONTAINER_REGISTRY/$PADV_IMAGE_NAME .

You can add other MathWorks products to the image by updating the MATLAB_PRODUCT_LIST argument. For the full list of products by release, see the mpm-input-files folder on GitHub^®.

MATLAB_PRODUCT_LIST='MATLAB Simulink Simulink_Check CI/CD_Automation_for_Simulink_Check Simulink_Design_Verifier Simulink_Report_Generator Simulink_Coder Simulink_Compiler Simulink_Test Embedded_Coder Simulink_Coverage Requirements_Toolbox'

For more information, see Create MATLAB Container Image.

Extend Image with Additional CI Tools for Pipeline Generation

You can create a Docker image that supports pipeline generation version 2 by adding the tools that the pipeline generator uses on top of your Docker image for the CI support package.

Pipeline generator version 2 supports specifying a single Docker image for running your generated pipeline. If you are using the pipeline generator to generate the CI pipeline files for your project, you can use these steps to add supporting tools, such as Python^®, Git™, JFrog CLI, Azure^® CLI, and AWS^® CLI.

Create a file, ci-addons.Dockerfile, that contains this code:

# Copyright 2025 The MathWorks, Inc.
ARG BASE_IMAGE=padv:latest

FROM ${BASE_IMAGE}

RUN export DEBIAN_FRONTEND=noninteractive \
    && sudo apt-get update \
    && sudo apt-get install --no-install-recommends --yes \
    python3 3.12 \
    python3-pip \
    git \
    curl \
    && sudo apt-get clean \
    && sudo apt-get autoremove \
    && sudo rm -rf /var/lib/apt/lists/*

RUN pip install colorlog

# Installing jfrog cli, azure cli and aws cli
RUN curl -fL https://getcli.jfrog.io/setup | sh
RUN curl -sL https://aka.ms/InstallAzureCLIDeb | sudo /bin/bash
RUN curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" && \
        sudo unzip awscliv2.zip && \
        sudo ./aws/install && \
        sudo rm -rf awscliv2.zip aws

ENTRYPOINT [""]

Note

Note that this code clears the ENTRYPOINT value to no longer require a virtual display to run. The example files use the MatlabLaunchCmd property of the pipeline generator options object to include the xvfb-run command as part of the call to launch MATLAB.

If you are using Azure DevOps, add the following lines before the final ENTRYPOINT instruction in ci-addons.Dockerfile. These commands are only required to meet the requirements for Azure DevOps container jobs.

###############################################
#      Support Azure DevOps container job
##############################################
# Install Node.js LTS and npm
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | sudo /bin/bash - \
    && sudo apt-get install -y nodejs \
    && sudo apt-get clean \
    && sudo rm -rf /var/lib/apt/lists/*

RUN sudo chmod u+s /usr/sbin/groupadd /usr/sbin/usermod && \
    sudo touch /etc/sudoers && \
    sudo chmod u+w /etc/sudoers && \
    sudo rm -f /bin/su && \
    sudo bash -c "echo '#!/usr/bin/env bash' > /bin/su" && \
    sudo bash -c "echo \"echo 'su has been disabled in this container'\" >> /bin/su"  && \
    sudo chmod +x /bin/su

ENTRYPOINT [""]

For other CI platforms, you do not need to add these commands.

Build a new image on top of the base Process Advisor image to include the additional CI tools and configuration to support the use of the image for pipeline generator version 2.
For example, you can use a PowerShell script to set common variables, specify the Docker image for the CI support package as the base image, and build the new image that installs the tools that pipeline generation version 2 requires.
```
$CONTAINER_REGISTRY = "<Container_Register_Domain>"
$PADV_IMAGE = "<Custom_Docker_Image_Name>"
$PADV_IMAGE_TAG = "<Custom_Image_Tag>"
$MATLAB_RELEASE = "R2025a"
$PADV_IMAGE_NAME = "${PADV_IMAGE}:${PADV_IMAGE_TAG}"

$CI_TAG = "ci"
$PADV_CI_IMAGE_NAME = "${PADV_IMAGE_NAME}_${CI_TAG}"

docker build -f ci-addons.Dockerfile `
    --build-arg BASE_IMAGE="$CONTAINER_REGISTRY/$PADV_IMAGE_NAME" `
    -t $CONTAINER_REGISTRY/$PADV_CI_IMAGE_NAME .
```

Configure Build Agents

Configure your build agents to use your container image. The approach varies depending on which CI platform you are using.

Azure DevOps

To use your container image with Azure DevOps:

Use a Linux build agent with Docker engine installed. Azure DevOps does not support the use of Linux container operations on Windows^® build agents.
Be careful when you select the user for the build agent. Azure DevOps container jobs use the agent user as the default container user. The standard MATLAB image runs as the matlab user with an ID of 1001, so you must configure your agent to use a user with a user ID of 1001.
Make sure the image user has permission to run privileged commands like groupadd without needing sudo. For more information, see the Azure DevOps documentation for Additional container requirements.

Note
If you used the ci-addons.Dockerfile to add tools for the pipeline generator, these permissions are already set up in the ci-addons.Dockerfile image layers.

GitHub

To use your container image with GitHub Actions, use a Linux build agent with a Docker engine installed. GitHub does not support container operations on Windows build agents.

GitLab

To use your container image with GitLab^® CI:

Use Linux-based Docker executors. For more information, see the GitLab documentation for Docker executor.

Review the configuration for allowed_images, allowed_pull_policies, and pull_policy configuration keys.

For example, the config.toml for your GitLab runner might contain a configuration such as this:

[[runners]]
  name = "runner_name"
  url = "http://gitlab.ci.local"
  id = 1
  token = "****-******_******"
  token_obtained_at = 2025-06-18T21:19:06Z
  token_expires_at = 0001-01-01T00:00:00Z
  [runners.docker]
    tls_verify = true
    image = "my.registry.tld:5000/ubuntu:latest"
    privileged = *
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = true
    volumes = ["/cache",]
    shm_size = 0
    allowed_pull_policies = ["always", "if-not-present"]
    pull_policy = "if-not-present"
    allowed_images = ["*:*", "*", "my.registry/*:*"]
    allowed_services = ["*:*"]

Jenkins

To use your container image with Jenkins^®:

Use the Docker plugin. The Jenkins Docker plugin does not support Linux container operations on Windows build agents due to workspace mapping mismatching.
Be careful when you select the user for the build agent. The Docker plugin for Jenkins uses the agent user as the default container user. The standard MATLAB image runs as the matlab user with an ID of 1001, so you must configure your agent to use a user with a user ID of 1001. Privilege mismatch is a common configuration issue where the user running a process inside a container does not match the bind-mount privileges it tries to access. You must maintain the user and its access to the host workspace. For example:
```

sudo groupadd -g 1001 matlab
sudo useradd -m -u 1001 -g 1001 matlab
sudo usermod -aG docker matlab
sudo passwd matlab

sudo -su matlab
```

Configure CI Pipeline

You can instruct version 2 of the pipeline generator to use your prebuilt Docker image. For information, see the pipeline generator version 2 example for your specific CI platform: