Tips for Setting Up CI Agents

A CI agent is a machine that is responsible for running MATLAB^® and communicating the results back to your chosen CI platform. Depending on the CI platform, you might set up the platform to run MATLAB on your own, self-hosted machine or in the cloud. Use the following suggestions to help set up your CI agent.

Product Installation

To use the support package in CI, you need to install at least these products on your CI agent:

MATLAB
Simulink^®
Simulink Check™
CI/CD Automation for Simulink Check
Any other products required by your process

You can programmatically install products by using the MATLAB Package Manager (MPM). For more information, see https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/MPM.md.

Note

License Considerations for CI: If you plan to perform CI on many hosts or in the cloud, contact MathWorks^® (continuous-integration@mathworks.com) for help. Transformational products such as MathWorks coder and compiler products might require client access licenses (CAL).

Dry-Run Your Process

Before you try to run your process on your CI agent, you can dry-run your process. The dry-run can validate your task inputs, generate representative task outputs, and make sure that you have the required licenses available on your CI agent.

To perform a dry-run, you can use the DryRun argument of the runprocess function. For example:

runprocess(DryRun = true)

To automatically check out the licenses associated with the tasks, you can specify the DryRunLicenseCheckout argument as true:

runprocess(DryRun = true, DryRunLicenseCheckout = true)

Dry-runs can be helpful for quickly testing out your CI pipeline and making sure that your required products and licenses are available, locally and on your CI agents. The built-in tasks now have a dryRun method that generates representative task outputs for each task. You can define your own custom dry-run functionality by overriding the dryRun method for class-based tasks or specifying the task property DryRunAction for function-based tasks.

Set Up Virtual Display Machines Without Displays

Some MATLAB code, including some built-in tasks, can only run successfully if a display is available for your machine. When there is no display available, MATLAB returns an error.

A machine might not have a display available if either:

You start MATLAB using the -nodisplay option.
The machine does not have a display configured and the DISPLAY environment variable is not set. For example:
- some CI runners
- some containers, including Docker^® containers by default
- machines that you SSH into without X11 forwarding

If MATLAB returns an error related to your display, try the following workaround.

You can set up a virtual display on the machine to simulate a display environment. The virtual display allows you to run MATLAB code that requires a display, without having to connect your machine to a physical display.

Choose a server. There are several common servers that you can install and use to host your virtual display, including:
- Xvfb — https://manpages.ubuntu.com/manpages/trusty/man1/xvfb-run.1.html
- VNC server — https://help.ubuntu.com/community/VNC/Servers
Install the server on the machine. For example, to install Xvfb on a Linux^® machine:
```
sudo apt-get install xvfb
```
Alternatively, for a containerized environment, you can instruct your container image to install and use the server as the display. For example, to install and use Xvfb for a Docker container, your Dockerfile can include:
```
RUN apt-get install --no-install-recommends --yes xvfb
RUN export DISPLAY=:`Xvfb -displayfd 1 &` && \
```
Tip
To access an example Dockerfile that uses Xvfb, enter the following command in MATLAB:
cd(fullfile(matlabshared.supportpkg.getSupportPackageRoot,... "toolbox","padv","samples"))
Run MATLAB in the server environment.
For example, with Xvfb on a Linux machine, you can use the xvfb-run command to run your MATLAB code with a virtual display. For example:
```
xvfb-run matlab -batch "openProject(projectPath);runprocess;"
```
For information, see https://manpages.ubuntu.com/manpages/trusty/man1/xvfb-run.1.html.
Note
Depending on which server you choose, you might need to manually start the server and set the DISPLAY environment variable on your machine to use your virtual display. The DISPLAY environment variable cannot be left empty.

Since most CI runners and containers do not have a display available, you should set up a virtual display server before you include the following built-in tasks in your process model:

Create Docker Container for Support Package

A container is an isolated unit of software that contains everything required to run a specific application. You can use a container as a scalable and reproducible way to deploy and test your process.

You can follow these steps to create a Docker image that includes MATLAB, other MathWorks products, and the CI/CD Automation for Simulink Check support package. The example Dockerfile installs the support package and other products by using the MATLAB Package Manager (MPM). Since certain MATLAB code requires a display to run successfully, the example Dockerfile uses Xvfb to set up a virtual display for the container.

The MATLAB Docker image is a Linux executable, but can run on any host operating system that Docker supports. For general information about MATLAB container images, see https://github.com/mathworks-ref-arch/matlab-dockerfile.

Install Docker on your machine. For information, see https://docs.docker.com/get-docker/.
To access the example Dockerfile for Process Advisor, open MATLAB and enter:
```
open(fullfile(matlabshared.supportpkg.getSupportPackageRoot,...
"toolbox","padv","samples","Dockerfile"))
```
Save a copy of the file, Dockerfile (no file extension), in a directory that your Docker daemon can access.
Build a Docker image by using the docker build command. You can use the build-time variables to specify the MATLAB release, MathWorks products, installation location, network license, and name for your container image. For example:
```
docker build --build-arg MATLAB_RELEASE=2023b 
--build-arg PRODUCTS="MATLAB Simulink Simulink_Check CI/CD_Automation_for_Simulink_Check" 
--build-arg MATLAB_INSTALL_LOCATION="/opt/matlab/R2023b" 
--build-arg LICENSE_SERVER=port@hostname 
-t my_matlab_image_name .
```
This example code only installs the products required by the support package. If you want to be able to run all of the built-in tasks, see the example Dockerfile for a list of the other products to add to the PRODUCTS list.
Use the build-arg LICENSE_SERVER to specify the port and hostname for your network license manager.
Alternatively, you can place your network.lic file in the same folder as the example Dockerfile, uncomment the line COPY network.lic ${MATLAB_INSTALL_LOCATION}/licenses in the example Dockerfile, and run the docker build command without the LICENSE_SERVER build-arg.
```
docker build --build-arg MATLAB_RELEASE=2023b 
--build-arg PRODUCTS="MATLAB Simulink Simulink_Check CI/CD_Automation_for_Simulink_Check" 
--build-arg MATLAB_INSTALL_LOCATION="/opt/matlab/R2023b" 
-t my_matlab_image_name .
```
For more information, see https://docs.docker.com/reference/cli/docker/image/build/ and https://github.com/mathworks-ref-arch/matlab-dockerfile.

Note
The example Dockerfile assumes that you are using the network license manager to license and run MATLAB. If you run MATLAB using a different licensing approach, contact MathWorks (continuous-integration@mathworks.com) for help.
Create and run a container from the generated image by using the docker run command.
```
docker run --init --rm my_matlab_image_name -batch "ver"
```
For information, see https://docs.docker.com/reference/cli/docker/container/run/.