Configure MATLAB in MATLAB Online Server

MATLAB^® Online Server™ enables you to set up different configurations of MATLAB that users can access. For example, you can specify configurations for each MATLAB release or different hardware resources available to each configuration. To set up and configure MATLAB:

Update the MATLAB Pool YAML files that correspond to the configurations of MATLAB you are setting up.
- If the server runs a single MATLAB configuration, see Set Up Single MATLAB Configuration.
- If the server runs multiple MATLAB configurations, see Set Up Multiple MATLAB Configurations.
For multiple MATLAB configurations, specify which release of the MATLAB documentation to serve across all configurations. See Specify MATLAB Documentation. MATLAB Online Server does not support specifying different MATLAB documentation releases for each configuration.
Deploy the changes. See Deploy MATLAB Configuration.

Prerequisites

You installed MATLAB Online Server and installed at least one configuration of MATLAB using one of the procedures listed under Installation.
You are familiar with core MATLAB Online Server concepts, such as MATLAB pools, pods, and YAML override files. For more details, see Host MATLAB Online on Your Infrastructure.

Set Up Single MATLAB Configuration

To set up a single MATLAB configuration running on the server, update the MATLAB Pool settings file that corresponds to that MATLAB configuration. The file is located at this path.

<server-root>/overrides/<cluster-name>/<namespace-name>/matlab-pool.yaml

<server-root> is the MATLAB Online Server installation folder.
<cluster-name> is the name of the Kubernetes^® cluster.
<namespace-name> is the namespace of the MATLAB Online Server deployment.

By modifying the YAML fields in this file, you can override the default MATLAB settings. This table shows the available configuration settings.

Configuration	Instructions
Configure License Server. Configure the MathWorks^® License Manager server used to check out MATLAB licenses.	In the `matlab-pool.yaml` file, in the `flexlm` field, update the `servers` subfield with the license server port and address information. Use the format `port@address`. For example: flexlm: servers: "27000@lm.acme.com" To list multiple servers, separate the server information with a colon. For example: flexlm: servers: "27000@lm1.acme.com:27000@lm2.acme.com"
Configure Prewarmed MATLAB Instances. Configure the number of prewarmed MATLAB instances that are ready for assignment when a user logs in.	In the `matlab-pool.yaml` file, update the `replicaCount` field. replicaCount: 2 The default count of `2` means that two MATLAB pods are ready for assignment. For example, suppose two users log in at the same time. Each pod assigned to them contains a MATLAB instance that is ready to use within seconds of logging in. If two more users log in at the same time, their logins are delayed until two new pods can start up. The maximum number of active users that can log in at one time is limited to the number of MATLAB licenses. The total number of MATLAB instances that can be assigned is limited to the number of licenses available and the hardware configured for the MATLAB Pool. If the server is unable to assign a MATLAB pod to a user, then the user receives a message that no MATLAB instances are available at that time and to try logging in later.
Customize Title Bar. Customize the MATLAB title bar text that displays on the browser tab when a user signs in.	In the `matlab-pool.yaml` file, update the `displayName` field. For example: poolConfig: displayName: "R2024b" This field accepts numbers, letters, dashes (`-`), underscores (`_`), and periods (`.`). For example: `"R2024b_4-CPU_16-GB"`. After the server establishes a MATLAB session, the display name appears as the title of the browser tab in this format: MATLAB Online – R2024b
Configure Network Policy. Configure additional ports that MATLAB has access to and the egress rules that apply, such as which applications MATLAB can connect to.	In the `networkPolicy` field of the `matlab-pool.yaml` file, uncomment the `additionalAllowedPorts` and `additionalEgress` sections and specify the additional ports and egress rules. For example: networkPolicy: enabled: true additionalAllowedPorts: - port: 1433 protocol: "TCP" - port: 1433 protocol: "UDP" additionalEgress: - to: - podSelector: matchLabels: name: "myapp-api" app: "myapp"
Set MATLAB Installation Source. Specify the source of the MATLAB Pool pod installation. MATLAB Online Server uses this information to mount the MATLAB installation so that it can interact with it.	In the `matlab-pool.yaml` file, update the `mountType` field to one of the mounting options described in Set MATLAB Installation Source.
Configure Storage. Configure the drives, directories, and files that are available to users after they log in to MATLAB.	In the `matlab-pool.yaml` file, define storage profiles for each resource available to users in separate `storage` fields, as described in Configure File Storage for Users in MATLAB Online Server.
Configure Hardware Resources. Allocate hardware resources and provide limits for memory and CPU configuration of MATLAB.	In the `matlab-pool.yaml` file, update the `resourceQuota` field, as described in Configure MATLAB Hardware Resources.
Configure GPU Support. Create a GPU node in your Kubernetes cluster and configure your MATLAB resource pools to deploy to that node.	See Configure GPU Support in MATLAB Online Server.
Configure Authorization. Customize which user groups can access MATLAB.	See Configure Group-Based Authorization in MATLAB Online Server.
Configure MATLAB Session Timeouts. Configure how long before MATLAB sessions time out.	In the `matlab-pool.yaml` file, in the `resourceDefinition` section, update these fields. Units are in minutes. resourceDefinition: maxLifetimeMinutes: 240 defaultLifetimeMinutes: 120 maxInactivityTimeoutMinutes: 30 defaultInactivityTimeoutMinutes: 15 For more details, see Configure MATLAB Session Settings.
Set Environment Variables and Metadata. Set MATLAB environment variables and pod metadata.	In the `matlab-pool.yaml` file, in the `resourceDefinition` section: To set Kubernetes tags, update the `podLabels` field. To set Kubernetes annotations, update the `podAnnotations` field. To set MATLAB environment variables, update the `env` field. Use this sample `matlab-pool.yaml` code and update the field values for your MATLAB pod. resourceDefinition: ownerMetadata: podLabels: - name: "username" value: "${subject.subjectId}" - name: "environment" value: "prod" podAnnotations: - name: "username" value: "${subject.subjectId}" env: - name: "MOS_USERNAME" value: "${subject.subjectId}" - name: "environment" value: "prod" The `${subject.subjectId}` format enables the `authnz` service to dynamically populate the user metadata when that user signs in. For more details about how placeholders work, see Placeholders.

Set Up Multiple MATLAB Configurations

When end users have access to multiple MATLAB configurations, after logging in, they are provided an option to choose the configuration they want to use (for example, R2024b, R2024b with GPU). The workflow for setting up multiple MATLAB configurations is as follows:

Enable the MATLAB chooser UI that end users see after logging in to MATLAB.
Create the folder structure used to store the MATLAB Pool YAML files for each MATLAB configuration.
Set up the MATLAB configuration that was initially installed with MATLAB Online Server.
Install and set up additional MATLAB configurations.

Enable MATLAB Configuration Chooser UI

The MATLAB chooser UI enables end users to select their configuration after signing in to MATLAB Online™. To enable the chooser UI, in the core-ui.yaml override file, set this field:

multiplePoolSupport: 
  enabled: true

The options that end users can choose from depend on how many and what kind of configurations you create. This sample UI chooser enables MATLAB end users to select from three different configurations of MATLAB Online.

Select MATLAB chooser with multiple configurations

When the end user clicks OK, MATLAB Online Server launches the selected configuration of MATLAB in the browser.

Create MATLAB Pool Folder Structure

To support multiple configurations of MATLAB, instead of specifying a single matlab-pool.yaml file, you must create a separate MATLAB Pool YAML file for each configuration. These files must reside in a folder named matlab-pool.

To set up this folder structure:

Navigate to the folder that contains the matlab-pool.yaml file. For example:
```
cd ~/matlab_online_server/overrides/matlab-online-server/mathworks
```
Create a directory named matlab-pool.
```
mkdir matlab-pool
```
Move the file matlab-pool.yaml to the matlab-pool directory.
```
mv matlab-pool.yaml matlab-pool
```

Set Up Installed MATLAB Configuration

Set up the configuration for the MATLAB version that you installed with MATLAB Online Server.

Rename the existing matlab-pool/matlab-pool.yaml file to matlab-pool/poolname.yaml, where poolname is a descriptive name of the pool. Typically, this name corresponds to the name of a MATLAB release, along with any additional characters that describe the pool. The name can include numbers, lowercase letters, hyphens (-), and periods (.). Uppercase letters are not permitted. For example:
- r2024a.yaml
- r2024a-gpu.yaml
In the renamed YAML file, specify any options for this MATLAB configuration. For a list of configurable options, see Set Up Single MATLAB Configuration.
Specify the display name that users see in the configuration chooser UI when they log in to MATLAB. The display name also appears in the title bar of the MATLAB Online browser. In the YAML file for this MATLAB pool, uncomment the poolConfig section and update the displayName field with a unique name for the release.
poolConfig: displayName: "R2024b"

Install and Set Up Additional MATLAB Configurations

After you set up the first MATLAB configuration, you can install and set up the additional MATLAB configurations. Repeat these steps for as many MATLAB configurations as you plan to support.

On the server, install the version of MATLAB you want to create a pool for by using the mosadm install-matlab command. For example:
```
sudo ./mosadm install-matlab --matlab-version <release-version>
```
If you are setting up a new configuration based off of an existing installation of MATLAB, skip this step.
Copy the YAML file you configured in Set Up Installed MATLAB Configuration. Rename this file based on the release and supported features of the MATLAB configuration. For example, the sample matlab-pool folder shown in supports three different configurations of MATLAB.
```
v mathworks
    v matlab-pool
        r2024a.yaml
        r2024a-gpu.yaml
    > namespace
    all.yaml
    authnz.yaml
    core-ui.yaml
    gateway.yaml
    license.yaml
    namespace.yaml
    resource.yaml
```
In the copied YAML file, configure any options for this new MATLAB pool. For a list of configurable options, see Set Up Single MATLAB Configuration.
In the YAML file, update the displayName field with the appropriate display name for that configuration. This name must be unique for each MATLAB pool you create.

Specify MATLAB Documentation

If your server includes only one MATLAB configuration, skip this step. Single MATLAB configurations serve the documentation corresponding to its release.

If your server supports multiple MATLAB configurations, then you must specify which release of the MATLAB documentation you want all configurations to serve. MATLAB Online Server does not support serving a different help release for each MATLAB configuration.

Select the configuration of MATLAB (for example, R2024b) from which you want to serve the help content. Open the respective YAML override file (for example, r2024b.yaml), and add the following field.
includeHelpSearch: true

Configure all MATLAB pools to use the help content from the selected configuration. In the all.yaml file, add the following fields.

extraMatlabStartupFlags: -r "docRelease=com.mathworks.mlservices.MLHelpServices.setDocRelease('RNNNNx');docRelease=com.mathworks.mlservices.MLHelpServices.getDocRelease;clear docRelease;"
includeHelpSearch: false

Replace RNNNNx with the MATLAB release you use for the help content, for example, R2024b.

Deploy MATLAB Configuration

To have your MATLAB configuration changes take effect, you must redeploy the MATLAB Pool configurations you updated. MATLAB users receive the changes the next time they sign on.

To redeploy all configurations of MATLAB running on the server, use the mosadm upgrade command.

./mosadm upgrade matlab-pool

If the server hosts only one MATLAB configuration, then this command redeploys the matlab-pool.yaml file for that configuration.
If the server hosts multiple MATLAB configurations, then this command redeploys all the YAML files for those configurations found in the matlab-pool folder.

To deploy newly installed MATLAB configurations, use the --install flag to deploy only that configuration and keep all currently deployed configurations running on the server.

./mosadm upgrade matlab-pool --install

If you modified YAML overrides files in addition to the MATLAB pool files, such as the core-ui.yaml file when specifying multiple MATLAB configurations, then you can redeploy the entire server by using mosadm deploy and mosadm undeploy.

./mosadm undeploy

./mosadm deploy