Perform Minimal MATLAB Online Server Installation on Single Machine

This topic explains the steps you must perform to set up MATLAB^® Online Server™ on a single machine for testing and evaluation. To add nodes to the cluster, see Production environment in the Kubernetes^® documentation.

After MATLAB Online Server is installed, individual MATLAB instances are hosted by a Docker^® container, 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 system requirements described in MATLAB Online Server System Requirements.
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.
You have Docker 20 or higher installed. For instructions on installing Docker for your Linux^® distribution, see Install Docker Engine in the Docker documentation.

Install Network License Manager

Follow the Linux instructions for installing on an offline machine described in Install License Manager on License Server in the Help Center. Configure the server to be accessed over the network.

You can use an existing network license server or create a new installation.
Ensure that the 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 server license hostname and ports using the MLM_LICENSE_FILE environment variable format of <port>@<host>[,<port>@<other-host>]. The hostname and port must be accessible from inside the Kubernetes cluster.
On your 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 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 Installer

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

Go to the Downloads page on mathworks.com.
Under Select Release, select the current release, for example R2023a.
Expand the Get MATLAB Online Server section. This section appears only if your account has a license for MATLAB Online Server software.
Click Download to download the ZIP file.
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 R2023a_matlab_online_server.zip -d ~/
```
The unzipped matlab_online_server folder is the root folder of your MATLAB Online Server installation. Navigate into 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
- data/
- install.config
- mosadm
- thirdpartylicenses.txt
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, modify these parameters.

Machine Configuration

Parameter Description Default

Parameter	Description	Default
`DOMAIN_BASE`	Fully qualified domain name used to access MATLAB Online Server from a web browser. For example: `matlabonline.mycompany.com`. Specifying an IP address as the domain base is not supported. It is recommended that the domain name is registered to your organization and that the IP address of the server or load balancer are available on the DNS server of the organization. To test that your domain is working, it is possible to temporarily update the host entry of your client machine to have the IP address and the fully qualified domain name. Then, you can test accessing MATLAB Online Server instance from a browser in your client using this domain name.	`matlab.domain.com`

DOMAIN_BASE

Fully qualified domain name used to access MATLAB Online Server from a web browser. For example: matlabonline.mycompany.com. Specifying an IP address as the domain base is not supported.

It is recommended that the domain name is registered to your organization and that the IP address of the server or load balancer are available on the DNS server of the organization.

To test that your domain is working, it is possible to temporarily update the host entry of your client machine to have the IP address and the fully qualified domain name. Then, you can test accessing MATLAB Online Server instance from a browser in your client using this domain name.

matlab.domain.com

Authentication Configuration

Parameter Description Default

Parameter	Description	Default
`ML_PASSWORD`	MATLAB Online™ sign-in password. The username for this bootstrapping mode is `admin`. For security purposes, it is recommended that you replace the default administration password with a more secure one. Identity provider configuration for authenticating MATLAB Online users is covered in Configure User Authentication in MATLAB Online Server.	`ML_PASSWORD=password`

ML_PASSWORD

MATLAB Online™ sign-in password.

The username for this bootstrapping mode is admin.

For security purposes, it is recommended that you replace the default administration password with a more secure one.

Identity provider configuration for authenticating MATLAB Online users is covered in Configure User Authentication in MATLAB Online Server.

ML_PASSWORD=password

License Configuration

Parameter Description Default

Parameter	Description	Default
`MOS_LICENSE_SERVER`	MATLAB Online Server license server. Specify the port and hostname IP address in the format `port@host`. Note If you have an Enterprise License, to correctly track usage, MathWorks requires two license servers: one for MATLAB Online Server (`MOS_LICENSE_SERVER` parameter) and one for MATLAB (`MATLAB_LICENSE_SERVER` parameter). With the two-server configuration, you must also have multiple pools (at least 2). See Configure Multiple Versions of MATLAB. Example: `14650@192.166.248.2`	`"27000@flexlm"`
`MATLAB_LICENSE_SERVER`	MATLAB license server details. Specify the port and hostname IP address in the format `port@host`. Example: `27000@172.0.0.1`	`"27000@flexlm"`

MOS_LICENSE_SERVER

MATLAB Online Server license server. Specify the port and hostname IP address in the format port@host.

Note

If you have an Enterprise License, to correctly track usage, MathWorks requires two license servers: one for MATLAB Online Server (MOS_LICENSE_SERVER parameter) and one for MATLAB (MATLAB_LICENSE_SERVER parameter).

With the two-server configuration, you must also have multiple pools (at least 2). See Configure Multiple Versions of MATLAB.

Example: 14650@192.166.248.2

"27000@flexlm"

MATLAB_LICENSE_SERVER

MATLAB license server details. Specify the port and hostname IP address in the format port@host.

Example: 27000@172.0.0.1

"27000@flexlm"

Additional Configuration Options

You can optionally modify additional parameters based on your configuration. For example, you can update the namespace to use for the deployment by updating the NAMESPACE parameter. 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 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.

sudo ./mosadm install-matlab

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.

For additional MATLAB installation options, see the mosadm install-matlab documentation. For example, you can install additional products or specify a specific MATLAB version to install.

Install Kubernetes and MATLAB Online Server

Download and install the required Kubernetes components, and install MATLAB Online Server on the installed Kubernetes cluster.

Create a single-node Kubernetes architecture.
```
sudo ./mosadm bootstrap-node
```
This command downloads and installs dependencies and the Kubernetes components. It then initializes a single-node Kubernetes cluster on the machine and customizes the cluster for MATLAB Online Server. It can take several minutes for the installation to finish.
By default, the Docker daemon is configured using the properties in the file /etc/docker/daemon.json, and the bootstrap-node command overwrites any customizations.
See mosadm bootstrap-node for more details on the bootstrap process.
To preserve existing customizations, use the following command instead.
```
sudo ./mosadm bootstrap-node --preserve-docker-config
```
At this step, you are asked to accept the terms and conditions for installing MATLAB Online Server. If you agree, answer "Y." If you do not, answer "N," which closes the installer. If you do not agree, you cannot install MATLAB Online Server.
To verify successful installation, confirm the existence of the /etc/kubernetes/admin.conf file. This file exists only after the cluster is created successfully.
```
ls /etc/kubernetes/admin.conf
```

Check that the pods are in the ready state. Each pods should have a READY state of 1/1 containers with a STATUS of Running. If you do not see the correct list of pods, check the version number for the install files. 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

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 and display the configuration options used for 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. mathworks is the default namespace used for the installation. 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

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

Log in to the MathWorks container registry, containers.mathworks.com, using your MathWorks account credentials.
```
sudo docker login containers.mathworks.com
```
Copy the necessary Helm^® charts from the 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
```
Load Docker images. This command loads the images from the MathWorks container registry into the local Docker cache.
```
sudo ./mosadm load-docker-images
```
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.

Configure Overrides

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

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
```
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

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 that you generate in the previous step.

Check that the services are all running with kubectl, replacing 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 fully start (2/2 containers). 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

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.
Open a browser on another machine and then go to the address where you are hosting MATLAB Online:
```
DOMAIN_BASE/matlabonline
```
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.