Run MATLAB code in Docker and Kubernetes

The official runmat/runmat image runs MATLAB-language scripts. Pipe a script into docker run on a laptop or a server, or run the image as a Kubernetes Job.

beam.m
% Tip deflection of a cantilever at five loads
loads = [1000 2000 3000 4000 5000]; % N
b = 0.035; h = 0.150; L = 1.5; E = 70e9; % m, m, m, Pa
d = 1e3*loads*L^3/(3*E*b*h^3/12); % mm
fprintf('%d of %d loads exceed the 6 mm limit\n', sum(d > 6), numel(loads));
terminal
$ docker run --rm -i runmat/runmat < beam.m
2 of 5 loads exceed the 6 mm limit

Why run it in a container

Nothing to activate

There is no license server to reach and no token to mount, so a container needs no setup before it runs a script.

A small image

The image is under 200 MB compressed. A program compiled with runmat compile fits in under 100 MB on its own.

Pinned and offline

Fetch your locked packages while the image builds and the container needs no network at run time. runmat.lock fixes every package version for each rebuild.

Laptop to cluster

Test an image on your laptop, then run that image in CI and on the cluster without changing it.

Run a script

Pipe a script into the container to run it. No mount or setup is needed.

Other runmat commands take the place of the script: runmat/runmat check analyze.m checks a file without running it, and docker run -it runmat/runmat repl opens an interactive session. The container runs as a non-root user.

terminal
docker run --rm -i runmat/runmat < beam.m
2 of 5 loads exceed the 6 mm limit

When the script reads or writes files, mount its folder at /work, the image's working directory, and name the script. Whatever it writes under /work lands back on the host.

terminal
docker run --rm -v "$PWD":/work runmat/runmat analyze.m
20 loads checked, 4 over the deflection limit
$ ls out
results.csv

Package a project you run often

When a project has helper functions and packages, and it runs on a schedule, in CI or across a cluster, build an image with the project and its locked packages inside. Each run then starts without fetching anything.

docker run beam-report runs the project's report entrypoint. Pass a script, such as one case of the sweep below, or another runmat command to run that instead.

Dockerfile
FROM runmat/runmat:0.6.3
WORKDIR /work
COPY runmat.toml runmat.lock ./
COPY src ./src
COPY scripts ./scripts
RUN runmat --locked package fetch
CMD ["run", "report"]
terminal
docker build -t beam-report .
docker run --rm beam-report
docker run --rm -e JOB_COMPLETION_INDEX=4 beam-report scripts/sweep.m

Batch, scheduled and sweep jobs on Kubernetes

Run the image as a Job when you need an answer once, a CronJob for a nightly report, or an Indexed Job to run every case of a sweep in parallel. Each pod reads JOB_COMPLETION_INDEX to pick its case.

scripts/sweep.m
% One case of the sweep: the Job's completion index picks the load
k = str2double(getenv('JOB_COMPLETION_INDEX'));
loads = 1000:500:5000;
P = loads(k + 1);
b = 0.035; h = 0.150; L = 1.5; E = 70e9;
d = 1e3*P*L^3/(3*E*(b*h^3/12));
fprintf('case %d: load %d N, deflection %.2f mm\n', k, P, d);
three of the nine pods
case 0: load 1000 N, deflection 1.63 mm
case 4: load 3000 N, deflection 4.90 mm
case 8: load 5000 N, deflection 8.16 mm

To spread one large run across nodes without writing a Job per case, use RunMat's own cluster scheduling. Parallel and cluster runs

sweep-job.yaml
apiVersion: batch/v1
kind: Job
metadata:
name: deflection-sweep
spec:
completionMode: Indexed
completions: 9
parallelism: 9
template:
spec:
restartPolicy: Never
containers:
- name: case
image: registry.example.com/beam-report:latest
args: ["scripts/sweep.m"]
resources:
requests: { cpu: "1", memory: 512Mi }

Use a GPU

On Linux, RunMat reaches the GPU through Vulkan, and the image includes the Vulkan loader. Give the container the GPU and its driver, and RunMat moves large array work to it.

To check, run d = gpuDevice in the container: backend reads vulkan and name names your GPU. Without a GPU, your code runs on the CPU unchanged.

Docker Desktop on macOS cannot pass the Apple GPU into a container. To use it, run RunMat on the Mac itself.

How RunMat uses the GPU
terminal
docker run --rm -i --gpus all \
-e NVIDIA_DRIVER_CAPABILITIES=compute,utility,graphics \
runmat/runmat < analysis.m

Needs the NVIDIA driver and the NVIDIA Container Toolkit on the host. graphics in the capabilities is what brings the Vulkan driver into the container.

Hand off a finished analysis

When an analysis is done and another team or a customer will run it, compile it with runmat compile and ship an image that holds just that program. It runs the analysis when it starts and is under 100 MB compressed.

Compile MATLAB code into an executable
Dockerfile
# Build stage: compile the analysis into one executable
FROM runmat/runmat:0.6.3 AS build
USER root
RUN apt-get update && apt-get install -y --no-install-recommends gcc libc6-dev
WORKDIR /src
COPY analyze.m .
RUN runmat compile analyze.m -o /analyze
# Run stage: only the executable
FROM ubuntu:24.04
COPY --from=build /analyze /usr/local/bin/analyze
RUN useradd --create-home --uid 10001 runmat
USER runmat
WORKDIR /work
ENTRYPOINT ["analyze"]

FAQ

01Does the container need a license server or token?

No. There is no license check, so there is nothing to mount or pass in.

02Can the container use a GPU?

Yes, on a Linux host with an NVIDIA, AMD or Intel GPU. Use a GPU above has the commands for each. On macOS, Docker Desktop cannot pass the Apple GPU into a container.

Use a GPURunMat on the GPU

03What is in the image?

Ubuntu 24.04, the release runmat binary (verified by SHA-256 when the image is built) and the Vulkan loader for GPUs. It runs as the non-root user runmat in /work, with runmat as the entrypoint, for linux/amd64 and linux/arm64. The image is under 200 MB compressed.

04How do I pin the version?

Use an exact tag such as runmat/runmat:0.6.3, or a minor tag such as runmat/runmat:0.6 for patch updates. Package versions are pinned by runmat.lock.

05Can I use it in CI?

Yes. Use it as the job's container image, or install RunMat on the runner instead.

RunMat in CI

06Why can't the container write to the mounted folder?

The image runs as uid 10001. Make the output folder writable for that user, or pass --user "$(id -u):$(id -g)" to run as yourself.

Run your first container

terminal
docker run --rm -i runmat/runmat < your_script.m
← Back to the runtime