Create Microservice Using Custom Base Layer

Supported Platforms: Windows®, Linux®, macOS

This example shows how to create a microservice Docker® image using a customized base layer. Creating a custom base layer allows you to use your preferred version of Linux or other operating system as the foundation and run commands or install additional dependencies.

Docker container images are composed of layers. In this example, you create three layers, each containing a set of file-system changes that build on top of the previous layers.

  1. Custom base layer (your chosen OS)

  2. Secondary layer (MATLAB® Runtime)

  3. Application layer (your microservice)

Prerequisites

Note

Some deployable archives, such as Simulink® Compiler™ artifacts, are not cross-platform compatible and must be built on Linux to use with Docker. For more information, see Limitations for MATLAB Compiler.

Create Production Server Archive Using compiler.build.productionServerArchive

In MATLAB, locate the MATLAB function that you want to deploy as a microservice. For this example, create the function mirror.m using the following code.

function out = mirror(in)
out = in;

Create a production server archive using compiler.build.productionServerArchive.

buildResults = compiler.build.productionServerArchive("mirror.m","Verbose",true);

Build Custom Base Layer Using Docker

You can customize the base layer using a Dockerfile.

For this example, create a new file named Dockerfile.customdeps. The file should specify the Linux distribution and install all of the dependencies required for MATLAB Runtime.

You can add commands to the Dockerfile to customize the behavior of the base layer. For example, add proxy information to the apt configuration file. 

RUN echo 'Acquire::http::Proxy "http://yourproxyaddress:proxyport";' >> /etc/apt/apt.conf

You can also install additional dependencies to fulfill any requirements for your deployment.

 Example Dockerfile.customdeps

Packages are sourced from https://github.com/mathworks-ref-arch/container-images/tree/main/matlab-runtime-deps/ for Ubuntu 24.04. If your internal OS image is derived from any other Linux distribution, you must recreate the list of dependencies for that OS.

At the MATLAB command window, build the custom base layer image using Docker and the Dockerfile you created.

depsImageName = "mycompanybase:r2024b";
system("docker build -f Dockerfile.customdeps -t " + depsImageName + " .");

Note

If you are using WSL, type wsl docker build instead.

Create Secondary Layer with MATLAB Runtime

Create a MATLAB Runtime Docker image layer that uses the custom base layer you created. Use name-value arguments to specify the base layer image and the MATLAB Runtime image name.

runtimeImageName = "custom-matlabruntime:r2024b";
compiler.runtime.createDockerImage(buildResults, ...
    "BaseImage",depsImageName, ...
    "ImageName",runtimeImageName)

Note

If you are unable to reach the Docker repositories, then you must first run compiler.runtime.createInstallerDockerImage with the path to the Linux MATLAB Runtime installer.

Create Application Layer by Packaging MATLAB Microservice

Create a microservice Docker image for the production server archive. Specify the name of the MATLAB Runtime Docker image you created as an input to the compiler.package.microserviceDockerImage function.

compiler.package.microserviceDockerImage(buildResults, ...
    "ImageName","mirror-micro","RuntimeImage",runtimeImageName);

You can deploy the microservice image using Docker and make calls to the service using any programming language that has HTTP libraries, including MATLAB Production Server™ client APIs.

For details about pushing your image to Docker Hub or your private registry, consult the Docker documentation.

Test Docker Image

Note

If Docker is running in a WSL2 session, preface the following commands with wsl.

  1. At the system command line, run the mirror-micro microservice image in Docker.

    docker run --rm -p 9900:9910 mirror-micro

    Port 9910 is the default port exposed by the microservice within the Docker container. You can map it to any available port on your host machine. For this example, it is mapped to port 9900.

    You can specify additional options in the Docker command. For a complete list of options, see Microservice Command Arguments.

  2. Once the container is running in Docker, you can check the status of the service by opening the following URL in a web browser: 

    http://hostname:9900/api/health

    Note

    Use localhost as the hostname if Docker is running on the same machine as the browser. If you are using Docker Desktop, you can access the container using host.docker.internal.

    If the service is ready to receive requests, you see the following message:

    "status:  ok"

  3. Test the running service. In the terminal, use the curl command to send a JSON query with the input argument 4 to the service through port 9900. For more information on constructing JSON requests, see JSON Representation of MATLAB Data Types (MATLAB Production Server).

    curl -v -H Content-Type:application/json -d '{"nargout":1,"rhs":[4]}' "http://<hostname>:9900/mirror/mirror"

    The output is the same as the input. 

    {"lhs":[{"mwdata":[4],"mwsize":[1,1],"mwtype":"double"}]}

    Note

    To use curl on Windows, use the following syntax: 

    curl -v -H Content-Type:application/json -d "{\"nargout\":1,\"rhs\":[4]}" "http://<hostname>:9900/mirror/mirror"

  4. To stop the service, use the following command to display the container id.

    docker ps
    CONTAINER ID       IMAGE              COMMAND                  CREATED            STATUS            PORTS                    NAMES
065546e98708       mirror-micro       "/opt/matlabruntime/…"   4 minutes ago      Up 4 minutes      0.0.0.0:9900->9910/tcp   silly_slaw

    Stop the service using the specified container id.

    docker stop 065546e98708

See Also

| |

Topics