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.
% Tip deflection of a cantilever at five loadsloads = [1000 2000 3000 4000 5000]; % Nb = 0.035; h = 0.150; L = 1.5; E = 70e9; % m, m, m, Pad = 1e3*loads*L^3/(3*E*b*h^3/12); % mmfprintf('%d of %d loads exceed the 6 mm limit\n', sum(d > 6), numel(loads));
$ docker run --rm -i runmat/runmat < beam.m2 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.
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.
docker run --rm -v "$PWD":/work runmat/runmat analyze.m
20 loads checked, 4 over the deflection limit$ ls outresults.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.
FROM runmat/runmat:0.6.3WORKDIR /workCOPY runmat.toml runmat.lock ./COPY src ./srcCOPY scripts ./scriptsRUN runmat --locked package fetchCMD ["run", "report"]
docker build -t beam-report .docker run --rm beam-reportdocker 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.
% One case of the sweep: the Job's completion index picks the loadk = 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);
case 0: load 1000 N, deflection 1.63 mmcase 4: load 3000 N, deflection 4.90 mmcase 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
apiVersion: batch/v1kind: Jobmetadata:name: deflection-sweepspec:completionMode: Indexedcompletions: 9parallelism: 9template:spec:restartPolicy: Nevercontainers:- name: caseimage: registry.example.com/beam-report:latestargs: ["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 GPUdocker 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.
# Build stage: compile the analysis into one executableFROM runmat/runmat:0.6.3 AS buildUSER rootRUN apt-get update && apt-get install -y --no-install-recommends gcc libc6-devWORKDIR /srcCOPY analyze.m .RUN runmat compile analyze.m -o /analyze# Run stage: only the executableFROM ubuntu:24.04COPY --from=build /analyze /usr/local/bin/analyzeRUN useradd --create-home --uid 10001 runmatUSER runmatWORKDIR /workENTRYPOINT ["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.
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.
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
docker run --rm -i runmat/runmat < your_script.m