Skip to content

Commit aae15b7

Browse files
aranegaaranega
committed
Add new README.md for the MATLAB image
1 parent deefda7 commit aae15b7

1 file changed

Lines changed: 148 additions & 0 deletions

File tree

‎images/matlab/README.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
# Dandi Docker Images
2+
3+
This folder contains the Dockerfile to build the MATLAB image for Dandi:
4+
5+
* `Dockerfile.matlab` provides a Nebari compatible jupyter environment with MATLAB(R) installed. This image requires you to bring your own licence.
6+
7+
## MATLAB Docker Image
8+
9+
The MATLAB Docker image relies on the [MATLAB Integration for Jupyter in a Docker Container](https://github.com/mathworks-ref-arch/matlab-integration-for-jupyter).
10+
It is shipped with [MATLAB-proxy](https://github.com/mathworks/matlab-proxy) which enables communication with MATLAB from a web-browser, and with [MATLAB-proxy-jupyter](https://github.com/mathworks/jupyter-matlab-proxy) which adds MATLAB integration for Jupyter.
11+
12+
This Dockerfile includes the following package, including platform products, toolbox products, and support packages from MathWorks® obtained via MATLAB Package Manager [(MPM)](https://www.mathworks.com/products/mpm.html), and additional add-on packages obtained from File Exchange and/or GitHub®
13+
14+
| # | Package | Source | Current Version | Projected Update Strategy |
15+
| --- | :--- | :---- | :--- | :--- |
16+
| 1 | MATLAB | MPM | R2025b | Penultimate MathWorks Release |
17+
| 2 | Bioinformatics Toolbox | MPM | R2025b | Penultimate MathWorks Release |
18+
| 3 | Computer Vision Toolbpx | MPM | R2025b | Penultimate MathWorks Release |
19+
| 4 | Curve Fitting Toolbox | MPM | R2025b | Penultimate MathWorks Release |
20+
| 5 | Deep Learning Toolbox | MPM | R2025b | Penultimate MathWorks Release |
21+
| 6 | Econometrics Toolbox | MPM | R2025b | Penultimate MathWorks Release |
22+
| 7 | Financial Toolbox | MPM | R2025b | Penultimate MathWorks Release |
23+
| 8 | Image Processing Toolbox | MPM | R2025b | Penultimate MathWorks Release|
24+
| 9 | Parallel Computing Toolbox | MPM | R2025b | Penultimate MathWorks Release |
25+
| 10 | Signal Processing Toolbox | MPM | R2025b | Penultimate MathWorks Release |
26+
| 11 | Statistics & Machine Learning Toolbox | MPM | R2025b | Penultimate MathWorks Release |
27+
| 12 | Wavelet Toolbox | MPM | R2025b | Penultimate MathWorks Release |
28+
| 13 | Deep Learning Toolbox Converter for TensorFlow Models | MPM | R2025b | Penultimate MathWorks Release
29+
| 14 | [MatNWB](https://github.com/NeurodataWithoutBorders/matnwb) | GitHub | v2.9.0 | Latest Release |
30+
| 15 | [Brain Observatory Toolbox](https://github.com/MATLAB-Community-Toolboxes-at-INCF/Brain-Observatory-Toolbox) | GitHub | v0.9.4.2 | Latest Release |
31+
| 16 | [Deep Interpolation Toolbox](https://github.com/MATLAB-Community-Toolboxes-at-INCF/DeepInterpolation-MATLAB) | GitHub | v0.9.1 | Latest Release |
32+
| 17 | [EXTRACT](https://github.com/schnitzer-lab/EXTRACT-public) | GitHub | Latest Commit | Latest Commit |
33+
| 18 | [CIATAH](https://github.com/bahanonu/ciatah) | GitHub | Latest Commit | Latest Commit |
34+
| 19 | [Example Live Scripts](https://github.com/MATLAB-Community-Toolboxes-at-INCF/example-live-scripts) | GitHub | Latest Commit | Latest Commit |
35+
36+
_Note:_ `EXTRACT` and `CIATAH` pull the latest commit from the git repository at Docker image build time. `Example Live Scripts` however pulls the latest commit from the git repository **the first time you start a MATLAB session** and only this first time. If you already have pulled a version and need to update to a more updated latest commit from the git repository open a console, then:
37+
38+
```bash
39+
cd example-live-scripts
40+
git pull
41+
```
42+
43+
If you have modified the existing examples, you might have to solve conflicts manually.
44+
45+
### How to Build
46+
47+
Building the MATLAB Docker image is straight forward.
48+
The following lines consider that you already cloned the repository and that you are positioned in the `docker` folder in the cloned repository on your file system.
49+
50+
```bash
51+
docker build -t dandi-matlab - < Dockerfile.matlab
52+
```
53+
54+
This will build the image tagging it as `dandi-matlab`.
55+
56+
### How to Run
57+
58+
Running a container for the built image requires that a port is passed to the command line to tell the container which internal port needs to be exposed and on which port to map it in the host system.
59+
60+
```bash
61+
docker run -p 8888:8888 dandi-matlab:latest
62+
```
63+
64+
This command considers the exposition of port `8888` and maps it to the port `8888` in the host.
65+
The syntax of the option is `-p [host port]:[container port]`.
66+
The port to expose in the container is always `8888`, but the host port can be changed to what is the best for your system.
67+
68+
After the container started, you can check the logs and you will see lines giving you the address you can open in your web browser to start the Jupyter instance.
69+
70+
```
71+
To access the server, open this file in a browser:
72+
file:///home/jovyan/.local/share/jupyter/runtime/jpserver-6-open.html
73+
Or copy and paste one of these URLs:
74+
http://78bd0f342a19:8888/lab?token=6bf3ad4d468ab3532fab610f5ff28dcf27b1b60300ec8e0c
75+
or http://127.0.0.1:8888/lab?token=6bf3ad4d468ab3532fab610f5ff28dcf27b1b60300ec8e0c
76+
```
77+
78+
To open locally the Jupyter, copy/paste the `127.0.0.1:8888/xxxxx` address in your browser.
79+
80+
CAUTION: If you changed the port on which will be mapped the internal container port, do not forget to change it also in the address you copy/paste from the logs.
81+
82+
### Closing your Session
83+
84+
Be careful while closing your session.
85+
If you don't close the session properly prior to stop your container, _i.e_: closing the MATLAB session and disconnecting yourself, there is chances that the MATLAB licencing system sees yourself as still connected and you'll have to wait the timeout of the session to be able to log/connect again after restarting the container.
86+
87+
To properly close your session, click on the `MATLAB Jupyter Setting` button which appears above the MATLAB top bar.
88+
From there, if you really want to close your session, clic on "Stop MATLAB Session", and if you really want to stop your Jupyter session, clic on "Sign Out".
89+
90+
### Add new Add-Ons
91+
92+
By default, the `Dockerfile.matlab` image is shipped with two addons already installed and accessible from MATLAB.
93+
You can easily add/remove addons by changing some lines in the Dockerfile: the addons links to download/install are defined by the `ARG ADDONS` variable.
94+
95+
CAUTION: The download links have to be release links towards `.zip` files.
96+
97+
#### How the Add-On Registration is Working
98+
99+
The add-ons registration is actually performed in two steps happening at two differents times: at "docker image construction" time, and at MATLAB startup time.
100+
101+
During the docker image construction, all add-ons referenced by the `ADDONS` variable in the Dockerfile are downloaded and extracted in a specific folder: `/opt/extras/dandi`.
102+
103+
At startup-time, this folder is automatically scanned by MATLAB and all downloaded add-ons are added to the "path" of MATLAB.
104+
The code responsible for the auto-scan of the add-ons folder is directly injected in the `startup.m` file during the docker image construction.
105+
If some add-ons require extra actions after being installed/added to the path, you can modify these lines to add extra action before the `clear`:
106+
107+
```dockerfile
108+
# Generate MATLAB startup script
109+
RUN echo -e "\n\
110+
% Set the number of workers for 'Processes' to 5\n\
111+
cluster = parcluster('Processes'); \n\
112+
cluster.NumWorkers = 5; \n\
113+
saveProfile(cluster); \n\
114+
\n\
115+
% Copy the live-example folder \n\
116+
homedirExamples = strcat(getenv('HOME'), '/example-live-scripts') \n\
117+
if not(isfolder(homedirExamples)) \n\
118+
repo = gitclone('https://github.com/MATLAB-Community-Toolboxes-at-INCF/example-live-scripts', homedirExamples, Depth=1); \n\
119+
end \n\
120+
% Add the example library to the path \n\
121+
addpath(homedirExamples); \n\
122+
% Add the addons to the path \n\
123+
addons = dir('${ADDONS_DIR}'); \n\
124+
addons = setdiff({addons([addons.isdir]).name}, {'.', '..'}); \n\
125+
for addon_idx = 1:numel(addons) \n\
126+
addpath(genpath(strcat('${ADDONS_DIR}/', addons{addon_idx}))); \n\
127+
end \n\
128+
% generateCore(); % Generate the most recent nwb-schema \n\
129+
% ciapkg.io.loadDependencies('guiEnabled', 0); % Load dependencies for CIAtah \n\
130+
% ADD HERE EXTRA ACTIONS FOR YOUR ADD-ON IF REQUIRED! \n\ <-- Starting here
131+
clear" >> ${STARTUP_SCRIPT}
132+
```
133+
134+
### Customize your Container
135+
136+
You can customize some parameter of your container changing some variables in the `Dockerfile.matlab`.
137+
138+
You can impact those parameters:
139+
140+
`ADDONS_DIR`:
141+
This variable defines where the add-ons must be downloaded/extracted and what will be the folder scanned by MATLAB at startup time.
142+
If you change this folder, the Jupyter user needs to have read/write access to it. This comes from a specificity of `matnwb` which requires the execution of some extra actions for its activation.
143+
144+
`ADDONS_RELEASE`:
145+
This variable defines the list of add-ons to download and install. You can add as much add-ons as you want as long as they are compatible with MATLAB-R25.
146+
147+
`ADDONS_LATEST`:
148+
This variable defines the list of add-ons to download and install directly from the lastest version identified in the github repository.

0 commit comments

Comments
 (0)