Main Content

Install MATLAB Online Server on Red Hat OpenShift

These instructions are for installing MATLAB® Online Server™ on the Red Hat® OpenShift® platform.

Verify Installation Prerequisites

Make sure your system meets the following requirements:

  • Push and pull access to the remote Docker® repository

  • Existing OpenShift 4.x cluster with:

    • Support for network policy

    • Service account that has access to "privileged" security context constraints.

      You can create this access with the following commands (the commands require the oc command tool):

>oc create namespace mathworks 
>oc create sa custom-sa --namespace mathworks 
>oc adm policy add-scc-to-user privileged -z custom-sa --namespace mathworks

Also complete the following software checks on the client machine before downloading and then configuring MATLAB Online Server.

  • Your client machine is running one of the supported operating systems and meets the minimum hardware and software requirements described in MATLAB Online Server System Requirements.

  • You can access the cluster’s kubeconfig file from the client machine.

  • Helm® 3 is installed.

  • kubectl is installed.

Note

These instructions include sudo for commands that by default require administration privileges. Depending on how your environment is configured, sudo might not be required in some cases.

Set Up Licensing

MATLAB Online Server requires two license servers: one for MATLAB Online Server and one for MATLAB. On each machine you plan to use as a license server, install an instance of the MathWorks® network license manager by following the offline Linux® instructions described in Install License Manager on License Server. Alternatively, you can use an existing license server. When setting up the license servers:

  • Configure each license server to be accessed over the network.

  • Make sure that MATLAB workers have access to their MathWorks licenses. Those licenses can be either co-located on the same license server or on independent servers.

  • Specify the MATLAB and MATLAB Online Server license hostnames and ports using the <port>@<host>[,<port>@<other-host>] format. The hostname and port must be accessible from inside the Kubernetes® cluster.

  • On each license server, add these lines to your license file to fix communication with the network license manager and the MLM daemon to ports 27000 and 27001, respectively.

    SERVER <HOSTID> ID=0 27000
    DAEMON MLM "<FLEXLM_INSTALL_LOCATION>/etc/MLM" port=27001

    By default, the MATLAB Online Server network policy enables access to these ports. Running the network license manager and MLM daemon on different ports is supported, but this configuration requires additional updates to your MATLAB Online Server network policy.

  • If you are restricting access to toolboxes or licenses by username, you must allow mwuser, the username of the license service that runs in the Kubernetes cluster, to check out licenses for MATLAB Online Server. In the etc folder of the network license manager for MATLAB Online Server, add this line to your MLM.opt options file:

    INCLUDE MATLAB_Online_Server USER mwuser

    Depending on how your organization configures accounts, you might need to create an mwuser account to enable the license options file.

If the license server is configured correctly, then the license service running in the Kubernetes cluster runs without any errors and checks out the license when it starts. If the license is invalid or the license server cannot be reached, then the license service exits and Kubernetes automatically attempts to restart the license service periodically until it succeeds.

The other services require that the license server is running, but if the license is temporarily unavailable, they continue to run. After an approximately two-hour grace period, the services go into a hibernation state and then reject requests with a failed status. The logs of the services indicate when they enter or exit this hibernation or grace period state.

If you encounter any issues with the license service, see Resolve License Service Issues.

Download MATLAB Online Server

Download Installer

Follow these steps to download and then extract the MATLAB Online Server installer and files.

  1. Go to the Downloads page on mathworks.com.

  2. Under Select Release, select the current release, for example, R2024a.

  3. Expand the Get MATLAB Online Server section. This section appears only if your account has a license for MATLAB Online Server software.

  4. Click Download to download the ZIP file.

  5. In the download folder or folder of your choice, extract the installation files. For example, this command downloads the ZIP file to your home directory (~/).

    unzip R2024a_matlab_online_server.zip -d ~/

    The unzipped matlab_online_server folder is the root folder of your MATLAB Online Server installation. Navigate to this folder. For example, if you unzipped the folder into your home directory, run this command.

    cd ~/matlab_online_server
    Confirm that this folder contains the following files and subfolders.
    ls

    • attributions.txt — Third-party software license attributions file, which is also included in each release container image

    • data — Folder that stores MATLAB Online Server data

    • install.config — File that contains properties for configuring your MATLAB Online Server installation

    • mosadm — Command-line executable for installing and configuring MATLAB Online Server

    • thirdpartylicenses.txt — Third-party software license file, which is also included in each release container image

    The mosadm command is the main utility to perform the remaining installation steps. You must run this command from your MATLAB Online Server installation folder. For details on the various operations it can perform, run this command.

    ./mosadm help

Configure Installation Properties

Edit the install.config file, located in the folder where you unzipped the installer, using a text editor such as nano.

nano install.config
Before editing this file, consider creating a backup of install.config so that you have a record of the default settings.

At a minimum, set these parameter values.

Configuration ParameterValue
DOMAIN_BASE

Fully qualified domain name for accessing MATLAB Online Server from a web browser. Specifying an IP address as the domain base is not supported.

Example: matlabonline.mycompany.com

DOCKER_REGISTRY

Remote Docker registry to push Docker images to

Example: myregistry.mycompany.com

DOCKER_REPOSITORY

Remote Docker repository

Example: mos

IMAGE_PULL_SECRET

User-friendly name for the Kubernetes secret object. When you deploy MATLAB Online Server, this object is created from registry credentials. This secret enables the nodes to pull images from the remote registry.

Example: mymossecret

ML_PASSWORDAdministrator password you want to use to log in to MATLAB Online™. The default is password.
MOS_LICENSE_SERVER

Port and hostname of your MATLAB Online Server license server. Use the port@host format.

Example: 27000@myhostname

MATLAB_LICENSE_SERVER

Port and hostname of your MATLAB license server. Use the port@host format.

Example: 27000@myhostname

Specify additional properties for your deployment as needed. For example, you can update the namespace to use for the deployment or enable TLS security. For a complete list of parameters, see Installation Configuration Properties.

Download and Install MATLAB

Download and install the version of MATLAB that your MATLAB Online users connect to.

  1. Download and install MATLAB by using the mosadm install-matlab command.

    The example shown here uses sudo, but if you have ownership of the installation folder and read and write privileges on it, sudo is not required. By default, mosadm install-matlab installs the latest version of MATLAB into the /MATLAB folder on your local machine. If the /MATLAB folder does not exist, the command creates it.

    sudo ./mosadm install-matlab

  2. (Required for MATLAB Online Server R2023a or later) Download and install the documentation for the MATLAB release you installed.

    1. Create a folder, /MATLAB/SupportPackages, to store the documentation that you download and install.

      mkdir /MATLAB/SupportPackages
    2. Start MATLAB from the /MATLAB/bin folder. If the command executes successfully, MATLAB exits automatically.

      sudo /MATLAB/bin/matlab -c MATLAB_LICENSE_SERVER -nosplash -nodesktop -batch "matlabshared.supportpkg.setSupportPackageRoot('/MATLAB/SupportPackages')"
      • -c MATLAB_LICENSE_SERVER specifies the port and hostname (port@host) of your MATLAB license server.

      • -nosplash and -nodesktop prevent the MATLAB splash screen from displaying and the MATLAB desktop from starting.

      • The -batch statement sets the support package root to the folder you created.

    3. Install the documentation to the support package root folder by following the instructions in Install Documentation on Permanently Offline Computers.

Install MATLAB Online Server

Load Docker Images

Load all Docker images and files shipped through the MathWorks container registry onto the computer.

  1. Copy the necessary Helm charts from the MathWorks container registry. Helm is an open source project that helps deploy services into Kubernetes. This command creates a folder named charts in the current folder and copies the charts there.

    sudo ./mosadm copy-helm-charts
  2. Load Docker images. This command loads the images from the MathWorks container registry into the local container cache.

    sudo ./mosadm load-docker-images

  3. List the images in the local cache to confirm that they loaded correctly.

    sudo ./mosadm list-docker-images
    Listing images
    containers.mathworks.com/matlab-online-server/mos-matlab-image:n.n.n
    ...
  4. From the local installation of MATLAB that you installed in the Download and Install MATLAB step, build an image containing MATLAB. This step can take several minutes.

    Note

    To build this image, your machine must have a TMPDIR environment variable that specifies a writable temporary directory mounted in exec mode. For details on applying this configuration, see Tips in the mosadm build-matlab-image documentation.

    sudo ./mosadm build-matlab-image /MATLAB

    Here, /MATLAB is the path to the folder containing your installation of MATLAB.

Push Docker Images to Image Registry

  1. Push the Docker images that you loaded in the previous step to the remote image registry that you specified in the install.config file.

    ./mosadm push-docker-images

  2. (Optional) To allow cluster nodes to pull these Docker images at deployment time, you must provide credentials to access the registry. If your cluster already has permissions for pulling images from the remote registry, then skip this step.

    Copy the registry credentials file into your MATLAB Online Server installation. If you have logged in to the remote registry from your client machine at least one time, then the file containing the registry credentials is located at ~/.docker/config.json. For example:

    cp ~/.docker/config.json ./dockerconfig.json

    The server uses contents from this file to create a Kubernetes secret with the name specified by the IMAGE_PULL_SECRET property of the install.config file.

Generate Override Files for Customizing Server

With the cluster and Docker images ready to use, load the server configuration override files. These YAML files enable you to override the default configuration of the server so that you can customize your server deployment.

  1. Generate the override files. Specify the --skip-matlab-image option to skip downloading the MATLAB Docker image locally. This image has already been pushed to your remote Docker repository.

    ./mosadm generate-overrides --skip-matlab-image

    The override files are generated to this folder:

    mosRoot/overrides/cluster/namespace
    • mosRootMATLAB Online Server root folder. Default: matlab_online_server

    • cluster — Name of server cluster. Default: matlab-online-server

    • namespace — Name of server namespace. Default: mathworks

  2. Confirm that the generated folder contains the following files.

    ls ./overrides/cluster/namespace
    • all.yaml — Configure global server settings

    • authnz.yaml — Configure user authentication and authorization

    • core-ui.yaml — Configure user interface elements, such as the MATLAB Online login screen

    • gateway.yaml — Configure the mapping between MATLAB Online Server clients and their assigned MATLAB instances

    • license.yaml — Configure communication with the license server

    • matlab-pool.yaml — Configure the MATLAB resource pool

    • namespace.yaml — Configure the namespace used to deploy MATLAB Online Server

    • resource.yaml — Configure access to storage resources

  3. Apply the necessary configuration updates to these override files.

    ConfigurationInstructions

    Allow Arbitrary User ID.  Allow OpenShift to choose an arbitrary user ID so that the server can set the container's user ID used to the one used to run MATLAB Online Server containers, as described in Security Considerations to Protect User Sessions in MATLAB Online Server. By default, OpenShift randomizes its container's User ID based on a range that differs by OpenShift project.

    In the all.yaml file, in the global field, set the allowArbitraryUserId subfield to true.

    global: 
      allowArbitraryUserId: true 

    Configure Ingress Controller.  OpenShift clusters come with an ingress controller, which you can use in MATLAB Online Server instead of the default NGINX ingress controller.

    In the all.yaml file, in the global field, add an ingressController section with the fields shown for your OpenShift version. MATLAB Online Server expects the timeout to be set to "365s" because the default timeout of openshift-ingress is not sufficient for MATLAB Online Server workflows.

    OpenShift 4.7 and Earlier

    global:
      ingressController:
        name: "openshift-ingress"
        annotations:
          haproxy.router.openshift.io/timeout: "365s"

    OpenShift 4.8 and Later

    global:
      ingressController:
        name: "openshift-default"
        annotations:
          haproxy.router.openshift.io/timeout: "365s"

    Enable Custom Service Account for MATLAB Pool.  The MATLAB pool pod needs to run with a specific user ID, as described in Security Considerations to Protect User Sessions in MATLAB Online Server. Because the pod also runs a privileged container to set up user storage and proxy to MATLAB, it needs to use a custom service account that has access to privileged security context constraints.

    In the matlab-pool.yaml file, add a customServiceAccount field with these subfields. In the name field, change the service account name to the name you created for the account.

    customServiceAccount: 
      enabled: true 
      name: "custom-sa"
    

    Disable AppArmor Security Module.  By default, MATLAB Online Server enables the Linux kernel security module AppArmor, which restricts the capabilities of services by account profile. This module is not supported on Red Hat and must be disabled.

    In the matlab-pool.yaml file, in the security field, set the apparmor.enabled subfield to false.

    security:
      apparmor:
        enabled: false 
    

    Configure Documentation.  (Required only for MATLAB Online Server R2023a or later) Enable the server to access the documentation that you installed to the /MATLAB/SupportPackages/help folder.

    In the matlab-pool.yaml file, in the matlab field, add a helpDocRoot subfield and specify the full path to the help folder.

    matlab:
      helpDocRoot: "/MATLAB/SupportPackages/help"

Deploy MATLAB Online Server

  1. To install all the MATLAB Online Server components, run the mosadm deploy command:

    ./mosadm deploy

    This command uses Helm to install all the charts, customized with any overrides from the previous step.

  2. Check that all services are running by using kubectl. Replace namespace with the namespace you used for MATLAB Online Server (default = mathworks). Depending on how you configured the server and the platform on which you installed the server, the exact pods you see might differ from the ones shown here.

    kubectl get pods --namespace namespace
    NAME                                                     READY   STATUS    RESTARTS   AGE
    namespace-authnz-7994c9866d-675fb                   1/1     Running   0          10m
    namespace-core-ui-cfdcccc4c-5bhrc                   1/1     Running   0          10m
    namespace-gateway-88ffd446d-mbf2l                   1/1     Running   0          10m
    namespace-gateway-proxy-6f85db9cbb-8ftbr            1/1     Running   0          10m
    namespace-gateway-proxy-6f85db9cbb-mdhr7            1/1     Running   0          10m
    namespace-license-5cc85b97cd-zg4vd                  1/1     Running   0          10m
    namespace-matlab-pool-9cc6b6465-9rdz8               2/2     Running   0          6m54s
    namespace-matlab-pool-9cc6b6465-t7wp2               2/2     Running   0          3m40s
    namespace-matlab-pool-helpsearch-8479fbdc88-4r6sd   1/1     Running   0          6m54s
    namespace-matlab-pool-ui-8484bbbd4d-t6777           1/1     Running   0          6m54s
    namespace-resource-78f9b97745-fzwlq                 1/1     Running   0          10m

The pods running MATLAB can take several minutes to start running. It is important to wait until the pods are in the ready state. If any of the containers do not start running, check the license server and the install.config settings. See Resolve MATLAB Pod Issues.

Configure DNS

After you install MATLAB Online Server, configure the domain name system (DNS) so that users when users access MATLAB Online from a browser, they are routed to the correct IP address.

  1. Get the external IP address of the cluster from the OpenShift ingress controller service. The IP address is returned in the External IP column of the command output.

    oc get services --namespace openshift-ingress
  2. Using an external DNS service (for example, Amazon® Route 53), route the DOMAIN_BASE parameter defined in install.config to this IP address.

Verify Installation

  1. Make sure the address in the DOMAIN_BASE parameter defined in install.config is registered and can be routed to the IP address of the host machine. Run this command, replacing DOMAIN_BASE with the value of the DOMAIN_BASE parameter:

    ping -c 1 DOMAIN_BASE

    This command returns the IP address of the host machine. In some types of installation, the ping does not receive packets. If you have such an installation, this command returns the IP address of the server you ping.

  2. Open a browser on another machine and then go to the address where you are hosting MATLAB Online:

    DOMAIN_BASE/matlabonline

  3. Your browser window displays the MATLAB Online login screen. For a single-machine installation, use the username admin and the password you specified in the ML_PASSWORD parameter of install.config (the default is password).

If you can now access your internal version of MATLAB Online, installation is complete. If you cannot access MATLAB Online, or you run into any other technical error, contact MathWorks Support.

Configure MATLAB Online Server

Complete the configuration steps required to set up the server for your organization.

  • Configure user authentication by specifying your identity provider details. See Authentication.

  • Configure persistent storage and which directories, drives, and files users can access. See Storage.

  • Configure your MATLAB installations or integrate other MathWorks products into the server. See MATLAB Configuration.

  • Set up monitoring and observability software on the server so that you can monitor the health of the server and troubleshoot issues as they arise. See Monitoring and Observability.

Related Topics