Introduces an optional dependency on the fluxbox window manager to support Simulink Online in Linux environments from MATLAB R2024b onwards.

fixes mathworks/jupyter-matlab-proxy#95
fixes #51

Author: prabhakk-mw

Advanced-Usage.md

@@ -32,7 +32,7 @@ The following table describes all the environment variables that you can set to
 | **MWI_CUSTOM_MATLAB_ROOT** | string (optional) | `"/path/to/matlab/root/"` | Optionally, provide a custom path to MATLAB root. For more information see [Adding MATLAB to System Path](#adding-matlab-to-system-path) |
 | **MWI_PROCESS_START_TIMEOUT** | integer (optional) | `1234` |  This field controls the time (in seconds) for which `matlab-proxy` waits for the processes it spins up, viz: MATLAB & Xvfb, to respond. By default, this value is `600 seconds`. A timeout could either indicate an issue with the spawned processes or be a symptom of a resource-constrained environment. Increase this value if your environment needs more time for the spawned processes to start.|
 | **MWI_MATLAB_STARTUP_SCRIPT** | string (optional) | `"addpath('/path/to/a/folder'), c=12"` | Executes string provided at MATLAB startup. For details, see [Run Custom MATLAB Startup Code](#run-custom-matlab-startup-code) |
-| **MWI_SHUTDOWN_ON_IDLE_TIMEOUT** | integer (optional) | 60 | Defines the duration in minutes, that `matlab-proxy` remains idle before shutting down. When you do not set the variable, `matlab-proxy` will not shutdown when idle. For details, [see Shutdown on Idle](#shutdown-on-idle).
+| **MWI_SHUTDOWN_ON_IDLE_TIMEOUT** | integer (optional) | 60 | Defines the duration in minutes, that `matlab-proxy` remains idle before shutting down. When you do not set the variable, `matlab-proxy` will not shut down when idle. For details, [see Shutdown on Idle](#shutdown-on-idle). |
 
 ## Shutdown on Idle
 
@@ -181,6 +181,6 @@ Note: Restarting MATLAB from within `matlab-proxy` will run the specified code a
 
 ----
 
-Copyright 2020-2024 The MathWorks, Inc.
+Copyright 2020-2025 The MathWorks, Inc.
 
 ----

README.md

@@ -3,11 +3,11 @@
 
 ----
 
-`matlab-proxy` is a Python® package which enables you to launch MATLAB® and access it from a web browser.
+Use this Python® package `matlab-proxy` to start MATLAB® and access it from a web browser.
 
-Installation of this package creates an executable `matlab-proxy-app`, which launches MATLAB and provides a URL to access it. 
+Install this package to create an executable `matlab-proxy-app`, which starts MATLAB and provides you a URL to access it. 
 
-The MATLAB Proxy is under active development. For support or to report issues, see the [Feedback](#feedback) section.
+MATLAB Proxy is under active development. For support or to report issues, see [Feedback](#feedback).
 
 ----
 
@@ -23,17 +23,19 @@ The MATLAB Proxy is under active development. For support or to report issues, s
 - [Feedback](#feedback)
 
 ## Requirements
-* MATLAB® R2020b or later is installed and on the system PATH.
+* MATLAB® R2020b or later, installed and added to the system PATH.
   ```bash
   # Confirm MATLAB is on the PATH
   which matlab
   ```  
 * The dependencies required to run MATLAB.
-  Refer to the Dockerfiles in the [matlab-deps](https://github.com/mathworks-ref-arch/container-images/tree/master/matlab-deps) repository for the desired version of MATLAB.
+  For details, refer to the Dockerfiles in the [matlab-deps](https://github.com/mathworks-ref-arch/container-images/tree/master/matlab-deps) repository for your desired version of MATLAB.
 
-* X Virtual Frame Buffer (Xvfb) : (only for Linux® based systems)
+* X Virtual Frame Buffer (Xvfb) (only for Linux® based systems):
+
+  Installing Xvfb is optional (starting v0.11.0 of matlab-proxy) but highly recommended. Xvfb enables graphical abilities like plots and figures in the MATLAB desktop. 
+  To install Xvfb on your Linux machine, use:
 
-  Install it on your linux machine using:
   ```bash
   # On a Debian/Ubuntu based system:
   $ sudo apt install xvfb
@@ -46,7 +48,17 @@ The MATLAB Proxy is under active development. For support or to report issues, s
   $ sudo yum install xorg-x11-server-Xvfb
   ```
 
-  *Note: The installation of Xvfb is **optional** (w.e.f. v0.11.0 of matlab-proxy). However, we highly recommend installing it.*
+
+* Fluxbox Window Manager (only for Linux® based systems):
+
+  Installing fluxbox is optional but required to use Simulink Online.
+
+  Install fluxbox using:
+  ```bash
+  # On a Debian/Ubuntu based system:
+  $ sudo apt install fluxbox 
+  ```
+
 * Python versions: **3.8** | **3.9**  | **3.10** | **3.11**
 * [Browser Requirements](https://www.mathworks.com/support/requirements/browser-requirements.html)
 * Supported Operating Systems:
@@ -84,7 +96,7 @@ which matlab-proxy-app
 
 Once the `matlab-proxy` package is installed.
 
-* Open a Linux terminal and launch the application with
+* Open a terminal and start `matlab-proxy-app`. On Linux, the command would be
   ```bash
   env MWI_BASE_URL="/matlab" matlab-proxy-app
   ```
@@ -131,7 +143,7 @@ The following options are available in the status panel (some options are only a
 
 ## Examples
 * For installing/usage in a Docker container, see this [Dockerfile](./examples/Dockerfile) and its [README](./examples/README.md).
-* For upgrading **matlab-proxy** in an existing Docker image, see this [Dockerfile.upgrade.matlab-proxy](./examples/Dockerfile.upgrade.matlab-proxy) and its [README](./examples/README.md#upgrading-matlab-proxy-package-in-a-docker-image).*
+* For upgrading **matlab-proxy** in an existing Docker image, see this [Dockerfile.upgrade.matlab-proxy](./examples/Dockerfile.upgrade.matlab-proxy) and its [README](./examples/README.md#upgrading-matlab-proxy-package-in-a-docker-image).
 * For usage in a Jupyter environment, see [jupyter-matlab-proxy](https://github.com/mathworks/jupyter-matlab-proxy).
 
 ## Platform Support
@@ -169,8 +181,10 @@ To install `matlab-proxy` in WSL 2, follow the steps mentioned in the [Installat
 `matlab-proxy` version `v0.7.0` introduces support for using an existing MATLAB license. Use the Existing License option only if you have an activated MATLAB. This allows you to start MATLAB without authenticating every time.
 
 ## Limitations
-This package supports the same subset of MATLAB features and commands as MATLAB® Online, except there is no support for Simulink® Online.
-[Click here for a full list of Specifications and Limitations for MATLAB Online](https://www.mathworks.com/products/matlab-online/limitations.html). 
+This package supports the same set of MATLAB features and commands as MATLAB® Online. For the full list, see 
+[Specifications and Limitations for MATLAB Online](https://www.mathworks.com/products/matlab-online/limitations.html). 
+
+Simulink Online is supported exclusively on Linux platforms starting from MATLAB R2024b.
 
 ## Security
 We take your security concerns seriously, and will attempt to address all concerns.

matlab_proxy/app_state.py

@@ -34,6 +34,7 @@
     OnlineLicensingError,
     UIVisibleFatalError,
     XvfbError,
+    WindowManagerError,
     log_error,
 )
 
@@ -548,7 +549,7 @@ def _are_required_processes_ready(
 
         if system.is_linux():
             # If Xvfb is on system PATH, check if it up and running.
-            if self.settings["is_xvfb_available"] and (
+            if self.settings.get("is_xvfb_available", None) and (
                 xvfb_process is None or xvfb_process.returncode is not None
             ):
                 logger.debug(
@@ -1000,11 +1001,6 @@ async def __setup_env_for_matlab(self) -> dict:
             f"MW_CONNECTOR_CONTEXT_ROOT is set to: {matlab_env['MW_CONNECTOR_CONTEXT_ROOT']}"
         )
 
-        # Setup Simulink Online which requires a pre-warm stage
-        if mwi_env.Experimental.is_simulink_enabled():
-            logger.info("Enabling usage of Simulink Online...")
-            matlab_env["PREWARM_SIMULINK"] = "true"
-
         # Env setup related to logging
         # Very verbose logging in debug mode
         if logger.isEnabledFor(logging.getLevelName("DEBUG")):
@@ -1052,6 +1048,31 @@ def __filter_env_variables(env_vars: dict, prefix: str) -> dict:
             key: value for key, value in env_vars.items() if not key.startswith(prefix)
         }
 
+    async def __start_window_manager(self, display=None):
+        if display is None:
+            logger.info("Not starting fluxbox as display is not provided")
+            return None
+
+        wm_env = os.environ.copy()
+        wm_env["DISPLAY"] = display
+        wm_cmd = ["fluxbox", "-screen", "0", "-log", "/dev/null"]
+
+        try:
+            logger.info(f"Starting window manager with DISPLAY={wm_env['DISPLAY']}")
+            return await asyncio.create_subprocess_exec(
+                *wm_cmd, close_fds=False, env=wm_env, stderr=asyncio.subprocess.PIPE
+            )
+
+        except Exception as err:
+            self.error = WindowManagerError(
+                "Unable to start the Fluxbox Window Manager due to the following error: "
+                + err
+            )
+            # Log the error on the console.
+            log_error(logger, self.error)
+
+        return None
+
     async def __start_xvfb_process(self):
         """Private method to start the xvfb process. Will set appropriate
         errors to self.error and return None when any exceptions are raised.
@@ -1073,7 +1094,7 @@ async def __start_xvfb_process(self):
             )
             self.settings["matlab_display"] = ":" + str(display_port)
 
-            logger.debug(f"Started Xvfb with PID={xvfb.pid} on DISPLAY={display_port}")
+            logger.info(f"Started Xvfb with PID={xvfb.pid} on DISPLAY={display_port}")
 
             return xvfb
 
@@ -1303,7 +1324,13 @@ async def start_matlab(self, restart_matlab=False):
 
             self.processes["xvfb"] = xvfb
 
+        # Start Window Manager on linux if possible
+        if system.is_linux() and self.settings["is_windowmanager_available"]:
+            display = self.settings.get("matlab_display", None)
+            await self.__start_window_manager(display)
+
         try:
+
             # Prepare ready file for the MATLAB process.
             self.create_logs_dir_for_MATLAB()
 

matlab_proxy/settings.py

@@ -218,6 +218,7 @@ def get_dev_settings(config):
         ),
         "warnings": [],
         "is_xvfb_available": False,
+        "is_windowmanager_available": False,
         "mwi_idle_timeout": None,
     }
 
@@ -271,12 +272,21 @@ def get(config_name=matlab_proxy.get_default_config_name(), dev=False):
         settings.update(get_server_settings(config_name))
 
         settings["is_xvfb_available"] = True if shutil.which("Xvfb") else False
+        settings["is_windowmanager_available"] = (
+            True if shutil.which("fluxbox") else False
+        )
 
         # Warn user if xvfb is not available on system path.
-        if system.is_linux() and not settings["is_xvfb_available"]:
-            warning = " Unable to find Xvfb on the system PATH. Xvfb enables graphical abilities like plots and figures in the MATLAB desktop.\nConsider adding Xvfb to the system PATH and restart matlab-proxy. See https://github.com/mathworks/matlab-proxy#requirements for information."
-            logger.warning(warning)
-            settings["warnings"].append(warning)
+        if system.is_linux():
+            if not settings["is_xvfb_available"]:
+                warning = "  Unable to find Xvfb on the system PATH. Xvfb enables graphical abilities like plots and figures in the MATLAB desktop.\nConsider adding Xvfb to the system PATH and restart matlab-proxy.\nFor details, see https://github.com/mathworks/matlab-proxy#requirements."
+                logger.warning(warning)
+                settings["warnings"].append(warning)
+
+            if not settings["is_windowmanager_available"]:
+                warning = " Unable to find fluxbox on the system PATH. To use Simulink Online, add Fluxbox to the system PATH and restart matlab-proxy. For details, see https://github.com/mathworks/matlab-proxy#requirements."
+                logger.warning(warning)
+                settings["warnings"].append(warning)
 
         settings.update(get_matlab_settings())
 

matlab_proxy/util/mwi/environment_variables.py

@@ -196,5 +196,5 @@ def get_env_name_profile_matlab_startup():
 
     @staticmethod
     def is_matlab_startup_profiling_enabled():
-        """Returns true if the simulink online is enabled."""
+        """Returns true if the startup profiling is enabled."""
         return _is_env_set_to_true(Experimental.get_env_name_profile_matlab_startup())

matlab_proxy/util/mwi/exceptions.py

@@ -1,4 +1,4 @@
-# Copyright 2020-2024 The MathWorks, Inc.
+# Copyright 2020-2025 The MathWorks, Inc.
 
 
 class AppError(Exception):
@@ -139,6 +139,19 @@ class XvfbError(AppError):
     pass
 
 
+class WindowManagerError(AppError):
+    """A Class which inherits the AppError class.
+
+    This class represents any errors raised when instantiating a Window Manager within the Xvfb DISPLAY.
+
+    Args:
+        AppError (Class): Parent Class containing attributes to store
+        messages, logs and stacktrace.
+    """
+
+    pass
+
+
 class EmbeddedConnectorError(MatlabError):
     """A Class which inherits the MatlabError class.
 

tests/unit/test_app_state.py

@@ -43,6 +43,7 @@ def sample_settings_fixture(tmp_path):
         "warnings": [],
         "matlab_config_file": tmp_file,
         "is_xvfb_available": True,
+        "is_windowmanager_available": True,
         "mwi_server_url": "dummy",
         "mwi_logs_root_dir": Path(settings.get_mwi_config_folder(dev=True)),
         "app_port": 12345,