MATLAB

Prerequisites

The minimum requirements for deploying your web application developed in MATLAB are as follows:

  • MATLAB R2022a or newer is required for Simian GUI
  • MATLAB Production Server
  • MATLAB Production Server Dashboard
  • MATLAB Runtime corresponding to the MATLAB release
  • MATLAB Compiler SDK
  • Redis is used as a caching mechanism between calls to the MATLAB Production Server

Deployment workflow

Setting up a MATLAB Production Server is thoroughly described in the Mathworks documentation.

Once your MATLAB Production Server is set up, deploying your application on it can be achieved through the following steps:

  1. Prepare your code for deployment.
  2. Compile your application into a deployable archive using MATLAB Compiler and MATLAB Compiler SDK.
  3. Deploy on MATLAB Production Server.
  4. Configure the Simian Portal to connect with the deployed code.

These items are described in more detail below.

Prepare your code for deployment

Before compiling your application into a deployable archive, the code must be made compilable. There are some things to take into consideration.

MATLAB Compiler supports most of the MATLAB language including objects, most MATLAB toolboxes, and user-developed user interfaces. The capabilities and limitations per toolbox are found in the Mathworks documentation. A non-exhaustive list of functions that are not supported for compilation by MATLAB Compiler and MATLAB Compiler SDK is found here.

Compile your application

First create a new function based on the entrypoint example function below, which will be the entry point for communication with your deployable archive. Make sure the namespace field of the metaData struct contains the namespace of your own form. Note that the simian.gui_v3_0_1 package contains a version number that may be different in the version you are including in your archive.

entrypoint.m

function payloadOut = entrypoint(operation, metaData, payloadIn)
    %% Entrypoint.
    % Containing package +my\+name\+space becomes "my.name.space".
    import simian.gui_v3_0_1.*;

    % Put package name into metaData (2nd input to callbackWrapper().
    metaData.namespace = "my.name.space";  % Replace with your own form namespace

    payloadOut = internal.callbackWrapper(operation, metaData, payloadIn);
end

The actual archive can be created in several ways described in the next two sections.

Using buildArchive utility

Compiling your application to a deployable archive can be done with the simian.gui_v3_0_1.buildArchive function (MATLAB R2020b+). The syntax is: results = simian.gui_v3_0_1.buildArchive(entrypointFcn, options) with entrypointFcn the absolute path to the entrypoint function and option a set of optional name-value pairs for compiler.build.ProductionServerArchiveOptions. For example:

root            = "C:\Files\BallThrower";
archiveName     = "BallThrower";
outDir          = fullfile(root, "CTFs");
entrypoint      = fullfile(root, "entrypoint.m");
additionalFiles = fullfile(root, ["+ballthrower", "@BallThrower"]);
results         = simian.gui_v3_0_1.buildArchive(entrypoint, ...
    "OutputDir", outDir, ...
    "ArchiveName", archiveName, ...
    "AdditionalFiles", additionalFiles);

This is equivalent to the following mcc command in MATLAB:

mcc("-W", "CTF:" + archiveName, ...
    "-d", outDir, ...
    "-Z", "autodetect", ...
    "-U", entrypoint, ...
    "-a", additionalFiles(1), "-a", additionalFiles(2), ...
    "-a", which("mps.cache.connect"), ...
    "-a", <rootOfSimianGui>\config.json, ...
    "-a", <rootOfSimianGui>\+simian\+gui_v3_0_1)

On MATLAB releases R2021b and newer, the buildArchive function outputs a compiler.build.productionServerArchive object. On releases R2020b and R2021a, the function outputs the mcc command that was executed by buildArchive.

The workflow for using this function is as follows:

  1. Select the entrypoint.m function as the first input of the buildArchive function.

  2. Define what folders and files must be included in the archive. This can be frontend and back-end code, but also for example static data. This set of folders and files constitutes the AdditionalFiles provided to buildArchive. The buildArchive function will automatically add the required Simian GUI folders and files to the archive for you (as well as Simian Wrapper code, if applicable), so these do not have to be specified in your AdditionalFiles.

  3. Call the buildArchive function to build the deployable archive.

Using MATLAB functionality

Aside from the buildArchive function, you can also use the MATLAB Production Server Compiler (MPS Compiler) or the MATLAB mcc function. The workflow is similar to using the buildArchive function:

  1. If you are using the MPS Compiler, the entrypoint.m function file should be selected as an "Exported Function". When using the mcc function, this function file should be one of the standard inputs.

  2. Add the code to the archive:

    • The package(s) and/or folder(s) with the form code and back-end code.
    • Done automatically by the buildArchive function, but a required step when using the MPS Compiler or mcc: The MATLAB Simian GUI's
      • config.json file
      • +simian package folder

    In the MPS Compiler, add these files and folders to the "Additional files" section. In the mcc function add these files using the -a option.

  3. Done automatically by the buildArchive function, but a required step when using the MPS Compiler or mcc: To enable caching to a Redis database, the following option needs to be added to the MPS Compiler's settings or the mcc function call:

    -a mps.cache.connect

  4. Create a new archive with these settings.

Deploy on MATLAB Production Server

Deployment of the created archives depends on the location and configuration of the MATLAB Production Server. This is documented in the MATLAB documentation in Deploy Archive to MATLAB Production Server and on other pages in the MATLAB documentation.

Configure Simian Portal

The deployed code must be made available from the Simian Portal by adding a configuration. This is documented in the Simian Portal Administration Guide available from the Simian Web apps documentation website.