Perform Offline MATLAB Online Server Installation
This topic explains how to install MATLAB® Online Server™ on a single machine in a restricted or air-gapped environment. In this workflow, you download and build software on an online machine, and then copy that software to the offline machine to complete the installation. The tags (Online Machine) and (Offline Machine) designate on which computer to perform the steps.
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:
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.
The offline machine is running one of the supported operating systems and meets the minimum hardware and software 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.
In addition, note the following:
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.
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.
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 <host-id> ID=0 27000 DAEMON MLM "<license-server-root>/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 theetc
folder of the network license manager for MATLAB Online Server, add this line to yourMLM.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.
(Online Machine) Download MATLAB Online Server
Download 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, R2024b.
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 R2024b_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.Confirm that this folder contains the following files and subfolders.cd ~/matlab_online_server
ls
attributions.txt
— Third-party software license attributions file, which is also included in each release container imagedata
— Folder that stores MATLAB Online Server datainstall.config
— File that contains properties for configuring your MATLAB Online Server installationmosadm
— Command-line executable for installing and configuring MATLAB Online Serverthirdpartylicenses.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
install.config
so that you have a record of the default settings.At a minimum, set these parameter values.
Configuration Parameter | Value |
---|---|
DOMAIN_BASE | Fully qualified domain name of the target offline machine. |
ML_PASSWORD | Administrator 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
Example:
|
MATLAB_LICENSE_SERVER | Port and hostname of your MATLAB license server. Use the
Example:
|
OFFLINE_MODE | true |
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
Build the offline installer for MATLAB Online Server with 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/data/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.
(Online Machine) Build MATLAB Image
Install MATLAB and build an image from that installation. Using this image, MATLAB Online Server creates MATLAB containers that your users connect to.
Install MATLAB
To install MATLAB, choose of these options:
Download and install MATLAB by using the
mosadm install-matlab
command. These sample commands usesudo
, but if you own and have read/write privileges on the MATLAB installation folder,sudo
is not required.(Basic installation) Install the latest MATLAB release into the folder
/MATLAB
on your computer. If this folder does not exist, the command creates it.sudo ./mosadm install-matlab
(Custom installation) Customize the installation folder, MATLAB release, or products to install. For example, this command installs the R2024b release of MATLAB and Simulink® into the
/opt/MATLAB
folder on your computer.sudo ./mosadm install-matlab --matlab-root /opt/MATLAB --matlab-version R2024b --products "MATLAB Simulink"
If you have a MATLAB ISO image, then use this ISO to install MATLAB directly on the offline machine. You can obtain an ISO image from MathWorks Downloads (requires internet connection).
Create a
/MATLAB
folder to use as the mount point for the ISO.mkdir /MATLAB
Mount the ISO to that folder. For instance, this command mounts the ISO located at
/opt/mathworks/matlab.iso
.mount -t iso9660 -o loop /opt/mathworks/matlab.iso /MATLAB
-t iso9660
identifies the file as an ISO image.-o loop
mounts the ISO image as a disk drive.
Run the install script located in that folder.
./MATLAB/install
(Required for MATLAB R2023a or later) Download and install the documentation for the MATLAB release you installed.
Create a folder,
/MATLAB/SupportPackages
, that will be used to store the documentation that you download and install.mkdir /MATLAB/SupportPackages
Start MATLAB from the
/MATLAB/bin
folder. If the command executes successfully, MATLAB exits automatically.sudo /MATLAB/bin/matlab -c <port@host of MATLAB license server> -nosplash -nodesktop -batch "matlabshared.supportpkg.setSupportPackageRoot('/MATLAB/SupportPackages')"
-c <port@host of MATLAB license-server>
specifies the port and hostname 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.
Install the documentation to the support package root folder by following the instructions in Install Documentation on Permanently Offline Computers.
Build Image from Installed MATLAB
Build an image containing this MATLAB installation. If you specified a custom MATLAB installation folder, replace /MATLAB
with the
custom folder path. This step can take several minutes.
sudo ./mosadm build-matlab-image /MATLAB
The resulting image is tagged as
containers.mathworks.com/matlab-online-server/mos-matlab-image
.
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.
(Online Machine) Copy MATLAB Online Server and MATLAB Image to Offline Machine
Copy the
matlab_online_server
folder to the offline server where you want to host MATLAB Online Server. The copied folder includes the MATLAB image you built. Sample command:scp -r matlab_online_server username@server.com:/home/$USER/matlab_online_server
Log off of the online machine.
Log in to the offline machine, and navigate to the
matlab_online_server
folder to continue the installation process.
(Offline Machine) Install Third-Party Software
Install Kubernetes
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.
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:
If you omitsudo ./mosadm bootstrap-node --preserve-docker-config
preserve-docker-config
, thenbootstrap-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.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
Check that the pods are in the ready state. Each pod should have a
READY
state of1/1
containers with aSTATUS
ofRunning
. 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 thekubectl
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 an 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
(Offline Machine) Install MATLAB Online Server
Install MATLAB Online Server and MATLAB, deploy the server, and verify that the installation was successful by signing in to MATLAB Online.
Load Docker Images
From the MathWorks container registry, load the required Docker images into the local container cache of your computer. List the images in this cache to confirm that they loaded correctly.
sudo ./mosadm load-docker-images
sudo ./mosadm list-docker-images
Listing images containers.mathworks.com/matlab-online-server/mos-matlab-image:n.n.n ...
Push Docker Images to Image Registry
Push the loaded and built Docker images to the local image registry. The mosadm
bootstrap-node
command creates this registry while installing Kubernetes. The registry location is specified by the DOCKER_REGISTRY
property of the install.config
file.
Push the Docker images to the remote registry.
sudo ./mosadm push-docker-images
(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 theinstall.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.
Generate the override files.
sudo ./mosadm generate-overrides
The override files are generated to this folder:
<server-root>/overrides/<cluster-name>/<namespace-name>
<server-root>
is the MATLAB Online Server root folder. Default:matlab_online_server
<cluster-name>
is the name of server cluster. Default:matlab-online-server
<namespace-name>
is the name of the server namespace. Default:mathworks
For example:
~/matlab_online_server/overrides/matlab-online-server/mathworks
Confirm that the generated folder contains the following files.
ls ./overrides/<cluster-name>/<namespace-name>
all.yaml
— Configure global server settingsauthnz.yaml
— Configure user authentication and authorizationcore-ui.yaml
— Configure user interface elements, such as the MATLAB Online login screengateway.yaml
— Configure the mapping between MATLAB Online Server clients and their assigned MATLAB instanceslicense.yaml
— Configure communication with the license servermatlab-pool.yaml
— Configure the MATLAB resource poolnamespace.yaml
— Configure the namespace used to deploy MATLAB Online Serverresource.yaml
— Configure access to storage resources
Apply the necessary configuration updates to these override files.
Configuration Instructions 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. If you specified a folder other than/MATLAB
when installing MATLAB, change/MATLAB
to that folder path.In the
matlab-pool.yaml
file, in thematlab
field, add ahelpDocRoot
subfield and specify the full path to thehelp
folder. Sample YAML:matlab: helpDocRoot: "/MATLAB/SupportPackages/help" installation: ...
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 from the previous step.
Check that all services are running by using
kubectl
. Replace<namespace-name>
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>
NAME READY STATUS RESTARTS AGE <namespace-name>-authnz-7994c9866d-675fb 1/1 Running 0 10m <namespace-name>-core-ui-cfdcccc4c-5bhrc 1/1 Running 0 10m <namespace-name>-gateway-88ffd446d-mbf2l 1/1 Running 0 10m <namespace-name>-gateway-proxy-6f85db9cbb-8ftbr 1/1 Running 0 10m <namespace-name>-gateway-proxy-6f85db9cbb-mdhr7 1/1 Running 0 10m <namespace-name>-license-5cc85b97cd-zg4vd 1/1 Running 0 10m <namespace-name>-matlab-pool-9cc6b6465-9rdz8 2/2 Running 0 6m54s <namespace-name>-matlab-pool-9cc6b6465-t7wp2 2/2 Running 0 3m40s <namespace-name>-matlab-pool-helpsearch-8479fbdc88-4r6sd 1/1 Running 0 6m54s <namespace-name>-matlab-pool-ui-8484bbbd4d-t6777 1/1 Running 0 6m54s <namespace-name>-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.
Get the external IP address of the cluster from the ingress controller service. If you installed the NGINX® ingress controller using
mosadm install-ingress
, to find the external IP address, use this command:kubectl get service --namespace mathworks
Using an external DNS service (for example, Amazon® Route 53), route the
DOMAIN_BASE
parameter defined ininstall.config
to this IP address.
Verify Installation
Make sure the address in the
DOMAIN_BASE
parameter defined ininstall.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 theDOMAIN_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 theML_PASSWORD
parameter ofinstall.config
(the default ispassword
).
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 and authorization by specifying your identity provider details. See Authentication and Authorization.
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.