Main Content

Perform Offline MATLAB Online Server Installation

This topic explains the steps you must perform to set up MATLAB® Online Server™ on a single machine in a restricted or air-gapped environment.

MATLAB Online Server installer provides a way to bootstrap a single-node Kubernetes® cluster on a node. However, this method pulls many third-party applications, for example, libraries, container images, and configuration files. This workflow might not work when network security measures meant to physically isolate the server from unsecure networks are employed.

Note the following:

  • The MATLAB Online Server single-machine installer assumes that the operating system is one of the Supported Platforms.

  • After MATLAB Online Server is installed, individual MATLAB instances are hosted by a container management tool, and the MATLAB Online Server stack is managed by Kubernetes.

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.

Verify Installation Prerequisites

Before beginning the installation, verify the following:

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

  • In this workflow, you build the offline installer on a separate node with internet access and transfer the installer to the offline machine. This online node must have the same configuration and OS version as the offline machine. The node requires internet access so that the installer can download Linux® packages for Kubernetes libraries specific to your installation, common Kubernetes Helm® charts and containers, and MathWorks® Helm charts and containers for MATLAB Online Server.

  • The offline machine is running in an air-gapped environment.

  • Your operating system is hosted at a static IP address. Kubernetes requires a static IP address to function properly. With dynamic IP addresses, when the IP address changes, the Kubernetes server fails and must be reinstalled.

Install Network License Manager

To install the network license manager, follow the Linux instructions for installing on an offline machine described in Install License Manager on License Server. Configure the server to be accessed over the network.

  • MathWorks requires two license servers: one for MATLAB Online Server and one for MATLAB.

  • You can use existing network license servers or create a new installation.

  • MATLAB workers must 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 and Install MATLAB on Offline Machine

Download MATLAB for offline installation, install the software on the offline server, and install the documentation in the support package root folder of MATLAB.

  1. Install MATLAB to the /MATLAB folder of the offline machine. See Install MathWorks Products on Offline Computer.

  2. After installation, create the support package root folder.

    mkdir /MATLAB/SupportPackages
  3. Open MATLAB from the /MATLAB/bin folder.

    /MATLAB/bin/matlab
  4. In MATLAB, set the support package root.

    matlabshared.supportpkg.setSupportPackageRoot('/MATLAB/SupportPackages')
  5. Restart MATLAB.

  6. Install the documentation to the support package root folder. See Install Documentation on Permanently Offline Computers.

Download MATLAB Online Server 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, R2023b.

  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 R2023b_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 MATLAB Online Server

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_BASEFully qualified domain name of the target offline machine.
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

OFFLINE_MODEtrue

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.

Build Offline Installer

Next, on the same machine, build the installer for MATLAB Online Server by entering the following command:

sudo ./mosadm build-offline-installer

This command downloads all the required artifacts for building the installer:

  • Kubernetes repo (for Kubernetes executables)

  • Yum repos configured on your system (RHEL® repos)

  • Docker® registry

    • Docker hub

    • gcr.io

  • Helm charts

    • GitHub®

For details about these artifacts, see the "Installed Utilities" section of Bootstrap Node for Ubuntu Systems.

After the installer finishes building, check that the following folders are present:

  • matlab_online_server/data/kubepacker-direct-install-baseimage-x.x.x/files/opt/mw/offlineinstaller/

  • matlab_online_server/3p.*

Check whether the build was successful by reading the terminal output. If the build was not successful, try rebuilding. If it fails again, contact MathWorks Support.

Copy MATLAB Online Server and MATLAB to Air-Gapped Machine

  1. Copy the matlab_online_server folder to the offline server where you want to host MATLAB Online Server. For example:

    scp -r matlab_online_server username@server.com:/home/$USER/matlab_online_server
  2. Copy your local MATLAB folder to the /MATLAB folder of the offline server. For example:

    scp -r matlab/R2023b username@server.com:/MATLAB
  3. Log off of the first machine and log in to the air-gapped machine.

Note

To continue with the installation, the OFFLINE_MODE parameter of the install.config file must be set to true, as described in the Configure MATLAB Online Server section.

Install Kubernetes and MATLAB Online Server

Use mosadm bootstrap-node to download and install the required Kubernetes components, initialize the single-node cluster, and install MATLAB Online Server on that cluster.

  1. Run the mosadm bootstrap-node command.

    • Default syntax:

      sudo ./mosadm bootstrap-node
    • Syntax to preserve existing Docker customizations, if you are using Docker as your container management tool:

      sudo ./mosadm bootstrap-node --preserve-docker-config
      If you omit preserve-docker-config, then bootstrap-node overwrites any existing customizations specified in the /etc/docker/daemon.json file of your Docker daemon.

    When prompted to accept the terms and conditions for installing MATLAB Online Server, enter "Y" to continue the installation process. The installation can take several minutes to complete.

  2. Verify the installation was successful by confirming that the /etc/kubernetes/admin.conf file exists. This file is created only when the cluster is created successfully.

    ls /etc/kubernetes/admin.conf

  3. Check that the pods are in the ready state. Each pod should have a READY state of 1/1 containers with a STATUS of Running. It can take several minutes for all pods to come online.

    sudo kubectl --kubeconfig /etc/kubernetes/admin.conf get pods --all-namespaces

    The command returns a display similar to the following.

    NAMESPACE     NAME                                       READY   STATUS    RESTARTS   AGE
    kube-system   coredns-78fde67838-m2spd                   1/1     Running   0          51s
    kube-system   etcd-ip-174-32-36-164                      1/1     Running   1          65s
    kube-system   kube-apiserver-ip-174-32-36-164            1/1     Running   1          65s
    kube-system   kube-controller-manager-ip-174-32-36-164   1/1     Running   1          68s
    kube-system   kube-router-w2mk4                          1/1     Running   0          52s
    kube-system   kube-scheduler-ip-174-32-36-164            1/1     Running   1          65s
  4. Merge the kube-config file into your home folder so that you can execute the kubectl command without having to specify the --kubeconfig /etc/kubernetes/admin.conf flag going forward.

    sudo ./mosadm merge-kube-config

Install NGINX Ingress Controller

The NGINX ingress controller processes incoming requests to the Kubernetes cluster and acts as a load balancer for MATLAB Online Server.

If you are using your own ingress controller, skip this step and see Configure NGINX Ingress Controller instead.

Install the controller by using the mosadm install-ingress command. The command displays the options it uses to configure the controller.

./mosadm install-ingress

# Config file for a ingress-nginx helm deploy
rbac:
  create: true

controller:
  hostNetwork: true
  ...

Verify that the controller is installed correctly. The default namespace for the installation is mathworks. You can customize this name in a later step.

kubectl get pods --namespace mathworks

NAME                                                  READY   STATUS    RESTARTS   AGE
mathworks-ingress-nginx-controller-7fdcd49d74-zngv4   1/1     Running   0          54s

Load Docker Images

  1. Load the Docker images from the built installer into the local Docker cache.

    sudo ./mosadm load-docker-images

  2. (Optional) Verify that you have enough disk space to build and load the MATLAB image by checking the size of your /MATLAB folder. Use the du (disk usage) command. For example:

    du /MATLAB --summarize --human-readable
  3. From the local installation of MATLAB that you installed in the Download and Install MATLAB on Offline Machine 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 local image registry that was created by the mosadm bootstrap-node command.

    sudo ./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 you do not use Docker for anything other than MATLAB Online Server, skip this step. The Docker configuration generated by the mosadm bootstrap-node command has the required permissions for pulling images from the local registry.

    If you use Docker for other applications, copy your existing registry credentials file into the 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.

Configure Overrides

With the cluster and Docker images ready to use, before the deploying the services, load the configuration overrides.

  1. Create the chart configuration files for the deployments. This command creates the YAML override files that you can use to configure the server in the overrides/cluster/namespace folder of your MATLAB Online Server installation, where:

    • cluster is the name of your cluster (matlab-online-server for single-node installations).

    • namespace is the value of the NAMESPACE parameter in your install.config file (default = mathworks).

    sudo ./mosadm generate-overrides
  2. Confirm that overrides/cluster/namespace contains the following files and subfolders.

    ls ./overrides/cluster/namespace

    • all.yaml

    • authnz.yaml

    • core-ui.yaml

    • gateway.yaml

    • license.yaml

    • matlab-pool.yaml

    • namespace.yaml

    • resource.yaml

The YAML files enable you to override the default configuration and customize the server. For example, you can configure storage and authentication. To customize the server before deployment, see Setup and Configuration. Otherwise, proceed to the next step.

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.

Verify MATLAB Online Server 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.

Set Up Server

With the installation process and initial configuration complete, you must now complete additional tasks to set up the server for use in your organization. For example, you need to:

  • Configure user authentication by specifying your identity provider details.

  • Configure the installed MATLAB versions and specify which user groups can access them.

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

  • Customize the MATLAB Online sign-in screen.

To get started setting up the server, see Set Up MATLAB Online Server After Installation.

Related Topics