Hi! As part of the OOD Appverse community, we're working to improve documentation consistency across Open OnDemand apps so that deployers at other sites can more easily evaluate, install, and adapt them.
We've put together a README template that covers the key sections deployers typically need when considering an app for their site.
After reviewing your current README, here's what we found:
Sections to add (not currently in your README):
- Screenshots
- Features
- Configuration (
form.yml attributes table)
- Troubleshooting
- Testing
- Known Limitations
- References
- Acknowledgments
Sections that could be expanded:
- Overview -- could mention app type (Batch Connect
vnc template), VirtualGL hardware rendering support, and link to the upstream MATLAB project
- Install -- could use the latest release tag (
v0.19.1), add form.yml configuration guidance for deployers at other sites, and include site-specific customization steps
- Prerequisites -- could add Open OnDemand version and note the
matlab group membership requirement from submit.yml.erb
Sections already present:
- Prerequisites (compute node software) -- well documented with MATLAB, Xfce, TurboVNC, websockify, X server, VirtualGL, and Lmod
- Contributing -- standard fork-and-PR workflow
- License -- dual-license (MIT for code, CC-BY-4.0 for docs) is clearly stated
Below we've provided two versions: a diff showing exactly what we're suggesting to add or change, and a clean copy-paste version you can drop in directly. Lines marked with <!-- TODO --> need your input -- we deliberately left those rather than guessing.
Diff view -- see exactly what's new and changed
# Batch Connect - OSC MATLAB
[](https://opensource.org/licenses/MIT)
- A Batch Connect app designed for OSC OnDemand that launches MATLAB within an
- Owens batch job.
+ ## Overview
+
+ An [Open OnDemand](https://openondemand.org/) Batch Connect app that launches
+ a [MATLAB](https://www.mathworks.com/products/matlab.html) desktop GUI via VNC
+ on OSC HPC clusters. MATLAB is a programming and numeric computing platform
+ used to analyze data, develop algorithms, and create models.
+
+ This app uses the Batch Connect `vnc` template with Slurm and supports
+ clusters: Pitzer and Cardinal.
+
+ - **Upstream project:** [MATLAB](https://www.mathworks.com/products/matlab.html)
+ - **Batch Connect template:** `vnc`
+ - **Scheduler:** Slurm
+
+ ## Screenshots
+
+ <!-- TODO: Add a screenshot of the app's launch form or a running session -->
+
+ ## Features
+
+ - Launches the MATLAB desktop GUI in a VNC session with Xfce window manager
+ - Multi-cluster support (Pitzer, Cardinal)
+ - Hardware rendering via VirtualGL on GPU/visualization nodes
+ - Multiple node types: standard compute (40/48 core), GPU, largemem, hugemem, debug
+ - Configurable core count and VNC resolution
+ - Multiple MATLAB versions available via the `matlab/` module (auto-detected)
+ - Group-based access control (requires `matlab` group membership)
+ - Module-based software loading via Lmod
- ## Prerequisites
+ ## Requirements
+
+ ### Compute Node Software
This Batch Connect app requires the following software be installed on the
**compute nodes** that the batch job is intended to run on (**NOT** the
OnDemand node):
- - [MATLAB] R2016b+
- - [Xfce Desktop] 4+
+ - [MATLAB](https://www.mathworks.com/) R2016b+
+ - [Xfce Desktop](https://xfce.org/) 4+
For VNC server support:
- - [TurboVNC] 2.1+
- - [websockify] 0.8.0+
+ - [TurboVNC](http://www.turbovnc.org/) 2.1+
+ - [websockify](https://github.com/novnc/websockify) 0.8.0+
For hardware rendering support:
- - [X server]
- - [VirtualGL] 2.3+
+ - [X server](https://www.x.org/)
+ - [VirtualGL](http://www.virtualgl.org/) 2.3+ (the app loads `virtualgl/3.1.1`
+ on GPU/vis nodes)
**Optional** software:
- - [Lmod] 6.0.1+ or any other `module purge` and `module load <modules>` based
+ - [Lmod](https://www.tacc.utexas.edu/research-development/tacc-projects/lmod) 6.0.1+ or any other `module purge` and `module load <modules>` based
CLI used to load appropriate environments within the batch job
- [MATLAB]: https://www.mathworks.com/
- [Xfce Desktop]: https://xfce.org/
- [TurboVNC]: http://www.turbovnc.org/
- [websockify]: https://github.com/novnc/websockify
- [X server]: https://www.x.org/
- [VirtualGL]: http://www.virtualgl.org/
- [Lmod]: https://www.tacc.utexas.edu/research-development/tacc-projects/lmod
+ ### Open OnDemand
+
+ <!-- TODO: Specify the minimum OOD version this app has been tested with -->
+ - Slurm scheduler
+ - Batch Connect VNC template support
+
+ ### Access Control
+
+ Users must be a member of the `matlab` group. The app checks group membership
+ at launch and will display an error if the user is not in the group.
- ## Install
+ ## App Installation
+
+ ### 1. Clone the repository
- Use git to clone this app and checkout the desired branch/version you want to
- use:
```sh
- scl enable git19 -- git clone <repo>
- cd <dir>
- scl enable git19 -- git checkout <tag/branch>
+ cd /var/www/ood/apps/sys
+ git clone https://github.com/OSC/bc_osc_matlab.git
+ cd bc_osc_matlab
+
+ # Pin to a release (recommended)
+ git checkout v0.19.1
```
- You will not need to do anything beyond this as all necessary assets are
- installed. You will also not need to restart this app as it isn't a Passenger
- app.
-
- To update the app you would:
-
- ```sh
- cd <dir>
- scl enable git19 -- git fetch
- scl enable git19 -- git checkout <tag/branch>
- ```
+ No restart is needed -- Batch Connect apps are not Passenger apps and are
+ detected automatically.
+
+ ### 2. Configure for your site
+
+ Edit `form.yml` and update these values for your cluster:
+
+ | Attribute | OSC Default | Change to |
+ |----------------------|---------------------------|----------------------------------|
+ | `cluster` | `pitzer`, `cardinal` | Your cluster name(s) |
+ | `auto_modules_matlab`| auto-detected MATLAB modules | MATLAB modules on your system |
+ | `node_type` | OSC-specific node types | Node types available on your cluster |
+ | `num_cores.max` | `28` | Max cores on your compute nodes |
+
+ In `script.sh.erb`, the app loads modules with:
+ ```
+ module load <matlab_module>
+ ```
+ On GPU/vis nodes it additionally loads:
+ ```
+ module load intel/16.0.3 virtualgl/3.1.1
+ ```
+ Update the versions to match what is available on your system.
+
+ In `submit.yml.erb`, the app checks for `matlab` group membership. Remove or
+ modify this check if your site has a different access control mechanism.
+
+ ### 3. Update the app
+
+ ```sh
+ cd /var/www/ood/apps/sys/bc_osc_matlab
+ git fetch
+ git checkout <tag>
+ ```
- Again, you do not need to restart the app as it isn't a Passenger app.
+ No restart is needed.
+
+ ## Configuration
+
+ ### form.yml attributes
+
+ | Attribute | Widget | Description | Default |
+ |----------------------|--------------|-------------------------------------------------------|-----------|
+ | `cluster` | select | Target cluster ID(s) | `pitzer`, `cardinal` |
+ | `auto_modules_matlab`| auto-select | MATLAB version module to load | auto-detected |
+ | `bc_num_hours` | number | Maximum wall time (hours) | <!-- TODO: specify default --> |
+ | `bc_num_slots` | hidden | Number of nodes (fixed) | `1` |
+ | `num_cores` | number_field | Number of CPU cores (1--28, varies by node type) | `1` |
+ | `node_type` | select | Compute node type (any, 48 core, 40 core, any gpu, 40 core gpu, 48 core gpu, largemem, hugemem, debug) | `any` |
+ | `bc_vnc_resolution` | text | VNC resolution (e.g., 1024x768) | required |
## Contributing
1. Fork it ( https://github.com/OSC/bc_osc_matlab/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request
+ For bugs or feature requests,
+ [open an issue](https://github.com/OSC/bc_osc_matlab/issues).
+
+ ## Troubleshooting
+
+ <!-- TODO: Add troubleshooting tips you've encountered -->
+
+ ## Testing
+
+ <!-- TODO: Update with sites where this app has been deployed -->
+
+ | Site | OOD Version | Scheduler | Status |
+ |---------------------------|----------------|-----------|------------|
+ | Ohio Supercomputer Center | <!-- TODO --> | Slurm | Production |
+
+ ## Known Limitations
+
+ <!-- TODO: Document any known limitations -->
+
+ ## References
+
+ - [MATLAB](https://www.mathworks.com/products/matlab.html) -- the application launched by this app
+ - [Open OnDemand](https://openondemand.org/) -- the HPC portal framework
+ - [OOD Batch Connect app development docs](https://osc.github.io/ood-documentation/latest/app-development.html)
+ - [Changelog](https://github.com/OSC/bc_osc_matlab/blob/master/CHANGELOG.md)
+ -- release history for this app
## License
* Documentation, website content, and logo is licensed under
[CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/)
* Code is licensed under MIT (see LICENSE.txt)
* MATLAB's logo is a trademark or registered trademark of MathWorks, Inc.
+ ## Acknowledgments
+
+ <!-- TODO: Add funding or institutional support information -->
Clean README.md -- copy-paste ready
# Batch Connect - OSC MATLAB
[](https://opensource.org/licenses/MIT)
## Overview
An [Open OnDemand](https://openondemand.org/) Batch Connect app that launches
a [MATLAB](https://www.mathworks.com/products/matlab.html) desktop GUI via VNC
on OSC HPC clusters. MATLAB is a programming and numeric computing platform
used to analyze data, develop algorithms, and create models.
This app uses the Batch Connect `vnc` template with Slurm and supports
clusters: Pitzer and Cardinal.
- **Upstream project:** [MATLAB](https://www.mathworks.com/products/matlab.html)
- **Batch Connect template:** `vnc`
- **Scheduler:** Slurm
## Screenshots
<!-- TODO: Add a screenshot of the app's launch form or a running session -->
## Features
- Launches the MATLAB desktop GUI in a VNC session with Xfce window manager
- Multi-cluster support (Pitzer, Cardinal)
- Hardware rendering via VirtualGL on GPU/visualization nodes
- Multiple node types: standard compute (40/48 core), GPU, largemem, hugemem, debug
- Configurable core count and VNC resolution
- Multiple MATLAB versions available via the `matlab/` module (auto-detected)
- Group-based access control (requires `matlab` group membership)
- Module-based software loading via Lmod
## Requirements
### Compute Node Software
This Batch Connect app requires the following software be installed on the
**compute nodes** that the batch job is intended to run on (**NOT** the
OnDemand node):
- [MATLAB](https://www.mathworks.com/) R2016b+
- [Xfce Desktop](https://xfce.org/) 4+
For VNC server support:
- [TurboVNC](http://www.turbovnc.org/) 2.1+
- [websockify](https://github.com/novnc/websockify) 0.8.0+
For hardware rendering support:
- [X server](https://www.x.org/)
- [VirtualGL](http://www.virtualgl.org/) 2.3+ (the app loads `virtualgl/3.1.1`
on GPU/vis nodes)
**Optional** software:
- [Lmod](https://www.tacc.utexas.edu/research-development/tacc-projects/lmod) 6.0.1+ or any other `module purge` and `module load <modules>` based
CLI used to load appropriate environments within the batch job
### Open OnDemand
<!-- TODO: Specify the minimum OOD version this app has been tested with -->
- Slurm scheduler
- Batch Connect VNC template support
### Access Control
Users must be a member of the `matlab` group. The app checks group membership
at launch and will display an error if the user is not in the group.
## App Installation
### 1. Clone the repository
```sh
cd /var/www/ood/apps/sys
git clone https://github.com/OSC/bc_osc_matlab.git
cd bc_osc_matlab
# Pin to a release (recommended)
git checkout v0.19.1
```
No restart is needed -- Batch Connect apps are not Passenger apps and are
detected automatically.
### 2. Configure for your site
Edit `form.yml` and update these values for your cluster:
| Attribute | OSC Default | Change to |
|----------------------|---------------------------|----------------------------------|
| `cluster` | `pitzer`, `cardinal` | Your cluster name(s) |
| `auto_modules_matlab`| auto-detected MATLAB modules | MATLAB modules on your system |
| `node_type` | OSC-specific node types | Node types available on your cluster |
| `num_cores.max` | `28` | Max cores on your compute nodes |
In `script.sh.erb`, the app loads modules with:
```
module load <matlab_module>
```
On GPU/vis nodes it additionally loads:
```
module load intel/16.0.3 virtualgl/3.1.1
```
Update the versions to match what is available on your system.
In `submit.yml.erb`, the app checks for `matlab` group membership. Remove or
modify this check if your site has a different access control mechanism.
### 3. Update the app
```sh
cd /var/www/ood/apps/sys/bc_osc_matlab
git fetch
git checkout <tag>
```
No restart is needed.
## Configuration
### form.yml attributes
| Attribute | Widget | Description | Default |
|----------------------|--------------|-------------------------------------------------------|-----------|
| `cluster` | select | Target cluster ID(s) | `pitzer`, `cardinal` |
| `auto_modules_matlab`| auto-select | MATLAB version module to load | auto-detected |
| `bc_num_hours` | number | Maximum wall time (hours) | <!-- TODO: specify default --> |
| `bc_num_slots` | hidden | Number of nodes (fixed) | `1` |
| `num_cores` | number_field | Number of CPU cores (1--28, varies by node type) | `1` |
| `node_type` | select | Compute node type (any, 48 core, 40 core, any gpu, 40 core gpu, 48 core gpu, largemem, hugemem, debug) | `any` |
| `bc_vnc_resolution` | text | VNC resolution (e.g., 1024x768) | required |
## Contributing
1. Fork it ( https://github.com/OSC/bc_osc_matlab/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request
For bugs or feature requests,
[open an issue](https://github.com/OSC/bc_osc_matlab/issues).
## Troubleshooting
<!-- TODO: Add troubleshooting tips you've encountered -->
## Testing
<!-- TODO: Update with sites where this app has been deployed -->
| Site | OOD Version | Scheduler | Status |
|---------------------------|----------------|-----------|------------|
| Ohio Supercomputer Center | <!-- TODO --> | Slurm | Production |
## Known Limitations
<!-- TODO: Document any known limitations -->
## References
- [MATLAB](https://www.mathworks.com/products/matlab.html) -- the application launched by this app
- [Open OnDemand](https://openondemand.org/) -- the HPC portal framework
- [OOD Batch Connect app development docs](https://osc.github.io/ood-documentation/latest/app-development.html)
- [Changelog](https://github.com/OSC/bc_osc_matlab/blob/master/CHANGELOG.md)
-- release history for this app
## License
* Documentation, website content, and logo is licensed under
[CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/)
* Code is licensed under MIT (see LICENSE.txt)
* MATLAB's logo is a trademark or registered trademark of MathWorks, Inc.
## Acknowledgments
<!-- TODO: Add funding or institutional support information -->
Feel free to use as much or as little of this as you'd like -- we're happy to discuss any of these suggestions or adjust them to better fit your project.
This review is part of the OOD Appverse Affinity Group documentation effort. If you're interested in collaborating on documentation standards for OOD apps, consider joining the Appverse Affinity Group.
Hi! As part of the OOD Appverse community, we're working to improve documentation consistency across Open OnDemand apps so that deployers at other sites can more easily evaluate, install, and adapt them.
We've put together a README template that covers the key sections deployers typically need when considering an app for their site.
After reviewing your current README, here's what we found:
Sections to add (not currently in your README):
form.ymlattributes table)Sections that could be expanded:
vnctemplate), VirtualGL hardware rendering support, and link to the upstream MATLAB projectv0.19.1), addform.ymlconfiguration guidance for deployers at other sites, and include site-specific customization stepsmatlabgroup membership requirement fromsubmit.yml.erbSections already present:
Below we've provided two versions: a diff showing exactly what we're suggesting to add or change, and a clean copy-paste version you can drop in directly. Lines marked with
<!-- TODO -->need your input -- we deliberately left those rather than guessing.Diff view -- see exactly what's new and changed
Clean README.md -- copy-paste ready
Feel free to use as much or as little of this as you'd like -- we're happy to discuss any of these suggestions or adjust them to better fit your project.
This review is part of the OOD Appverse Affinity Group documentation effort. If you're interested in collaborating on documentation standards for OOD apps, consider joining the Appverse Affinity Group.