Improve README to match Appverse documentation standard #1
Description
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):
- Overview (expanded description with app type, upstream link, and technical summary)
- Screenshots
- Features
- Requirements (compute node software, OOD version)
- App Installation (clone, configure, verify)
- Configuration (
form.yml.erbattributes table) - Troubleshooting
- Testing
- Known Limitations
- Contributing
- References
- Acknowledgments
Sections that could be expanded:
- Title and description -- could mention the Batch Connect
basictemplate, Slurm scheduler,matlab-proxyweb server, and link to the upstream MATLAB project
Sections already present:
- Title -- clear app name
- Contact information -- maintainer name and email
- Brief description -- identifies the app and the DEAC cluster
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
- # Matlab App for Open OnDemand (OOD)
+ # MATLAB App for Open OnDemand (OOD)
- Wake Forest University (WFU) HPC Team<br>
- Primary Contact: Sean Anderson (anderss@wfu.edu)<br>
-
- This is WFU's Matlab app for DEAC OnDemand.
+ ## Overview
+
+ An [Open OnDemand](https://openondemand.org/) Batch Connect app that launches
+ [MATLAB](https://www.mathworks.com/products/matlab.html) as an interactive web
+ server session on HPC clusters using
+ [matlab-proxy](https://github.com/mathworks/matlab-proxy). MATLAB is a
+ programming and numeric computing platform used for data analysis, algorithm
+ development, and modeling.
+
+ This app uses the Batch Connect `basic` template to run `matlab-proxy-app` as
+ a reverse-proxied web server on a compute node with token-based authentication.
+ Python 3.11.8 is loaded alongside the selected MATLAB version to provide the
+ `matlab-proxy` web server.
+
+ Developed by the Wake Forest University (WFU) HPC Team.
+ Primary Contact: Sean Anderson (anderss@wfu.edu)
+
+ - **Upstream project:** [MATLAB](https://www.mathworks.com/products/matlab.html)
+ - **Web proxy:** [matlab-proxy](https://github.com/mathworks/matlab-proxy)
+ - **Batch Connect template:** `basic`
+ - **Scheduler:** Slurm
+ - **Cluster:** DEAC
+
+ ## Screenshots
+
+ <!-- TODO: Add a screenshot of MATLAB running in the browser session -->
+
+ ## Features
+
+ - Launches MATLAB GUI in a web browser via `matlab-proxy-app` on compute nodes
+ using Batch Connect `basic` template
+ - Token-based authentication for secure sessions
+ - Auto-shutdown on idle (360 second timeout)
+ - Multiple MATLAB versions available (R2023b, R2024a)
+ - Configurable Slurm account, partition, node type, cores, memory, and GPUs
+ via the launch form
+ - Working directory selector
+ - Optional additional environment modules can be loaded at launch time
+ - Multiple CPU and GPU node types supported (AMD Zen3/Zen4, Intel Cascade
+ Lake/Skylake, A100, V100)
+ - Modules loaded at runtime: `apps/python/3.11.8` + selected MATLAB version
+
+ ## Requirements
+
+ ### Compute Node Software
+
+ - [MATLAB](https://www.mathworks.com/products/matlab.html) available as an
+ environment module (currently `apps/matlab/2023b` and `apps/matlab/2024a`)
+ - [matlab-proxy](https://github.com/mathworks/matlab-proxy) Python package
+ installed (provides `matlab-proxy-app`)
+ - Python 3 available as an environment module (currently `apps/python/3.11.8`)
+ - [Environment Modules](https://modules.readthedocs.io/) with init at
+ `/usr/share/Modules/init/bash`
+ - Valid MATLAB license accessible from compute nodes
+
+ ### Open OnDemand
+
+ <!-- TODO: Specify the minimum OOD version this app has been tested with -->
+ - Slurm scheduler
+
+ ## App Installation
+
+ ### 1. Clone the repository
+
+ ```sh
+ cd /var/www/ood/apps/sys
+ git clone https://github.com/WFU-HPC/OOD-apps.server.matlab.git
+ cd OOD-apps.server.matlab
+ ```
+
+ ### 2. Configure for your site
+
+ Edit `form.yml.erb` and update these values for your cluster:
+
+ | Attribute | WFU Default | Change to |
+ |-------------|----------------------------------------|------------------------------------|
+ | `cluster` | `"deac"` | Your cluster name |
+ | `version` | `"apps/matlab/2023b"`, `"apps/matlab/2024a"` | MATLAB module paths on your system |
+ | `accounts` | WFU Slurm accounts | Your Slurm accounts |
+ | `queues` | `"small"` | Your Slurm partitions |
+ | `node_type` | WFU-specific node types | Node types on your cluster |
+
+ You will also need to update `submit.yml.erb` if your cluster uses different
+ Slurm constraint names or node configurations.
+
+ In `script.sh.erb`, the app loads:
+ ```
+ module load apps/python/3.11.8
+ module load apps/matlab/2024a
+ ```
+ Ensure equivalent modules with `matlab-proxy` installed are available on
+ your system.
+
+ ### 3. Verify
+
+ No OOD restart is needed (Batch Connect apps are detected automatically).
+ Visit your OOD dashboard and look for **MATLAB** under
+ **Interactive Apps > Math and Statistics**.
+
+ ## Configuration
+
+ ### form.yml.erb attributes
+
+ | Attribute | Widget | Description | Default |
+ |------------------------|-----------------|-----------------------------------------------|----------------------------|
+ | `version` | select | MATLAB version to load | `"apps/matlab/2023b"` |
+ | `enable_extra_modules` | check_box | Toggle extra module loading | unchecked |
+ | `extra_modules` | text_field | Additional environment modules to load | `""` |
+ | `working_dir` | path_selector | Working directory for the session | User's `$HOME` |
+ | `accounts` | select | Slurm account for job submission | (dynamic from cluster) |
+ | `queues` | select | Slurm partition | `"small"` |
+ | `bc_num_hours` | number | Maximum wall time (hours) | `1` |
+ | `num_cores` | number_field | Number of CPU cores | `1` |
+ | `memory` | number_field | Memory in GB | `8` |
+ | `node_type` | select | Compute node type (CPU, GPU, specific HW) | Any (shortest wait) |
+ | `num_gpus` | number_field | Number of GPUs (for GPU node types) | `0` |
+
+ ## Troubleshooting
+
+ <!-- TODO: Add troubleshooting tips -->
+
+ ## Testing
+
+ <!-- TODO: Update with sites where this app has been deployed -->
+
+ | Site | OOD Version | Scheduler | Status |
+ |-------------------------------|---------------|-----------|--------|
+ | Wake Forest University (DEAC) | <!-- TODO --> | Slurm | <!-- TODO --> |
+
+ ## Known Limitations
+
+ <!-- TODO: Document any known limitations -->
+
+ ## Contributing
+
+ Contributions are welcome. To contribute:
+
+ 1. Fork this repository
+ 2. Create a feature branch (`git checkout -b feature/my-improvement`)
+ 3. Submit a pull request with a description of your changes
+
+ For bugs or feature requests,
+ [open an issue](https://github.com/WFU-HPC/OOD-apps.server.matlab/issues).
+
+ ## References
+
+ - [MATLAB](https://www.mathworks.com/products/matlab.html) -- the computing
+ platform launched by this app
+ - [matlab-proxy](https://github.com/mathworks/matlab-proxy) -- the Python
+ package providing the web proxy server
+ - [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)
+
+ ### Software Installation
+
+ <!-- TODO: Add notes about installing MATLAB and matlab-proxy on your compute nodes -->
+
+ ## License
+
+ [MIT License](LICENSE)
+
+ ## Acknowledgments
+
+ <!-- TODO: Add funding or institutional support information -->Clean README.md -- copy-paste ready
# MATLAB App for Open OnDemand (OOD)
## Overview
An [Open OnDemand](https://openondemand.org/) Batch Connect app that launches
[MATLAB](https://www.mathworks.com/products/matlab.html) as an interactive web
server session on HPC clusters using
[matlab-proxy](https://github.com/mathworks/matlab-proxy). MATLAB is a
programming and numeric computing platform used for data analysis, algorithm
development, and modeling.
This app uses the Batch Connect `basic` template to run `matlab-proxy-app` as
a reverse-proxied web server on a compute node with token-based authentication.
Python 3.11.8 is loaded alongside the selected MATLAB version to provide the
`matlab-proxy` web server.
Developed by the Wake Forest University (WFU) HPC Team.
Primary Contact: Sean Anderson (anderss@wfu.edu)
- **Upstream project:** [MATLAB](https://www.mathworks.com/products/matlab.html)
- **Web proxy:** [matlab-proxy](https://github.com/mathworks/matlab-proxy)
- **Batch Connect template:** `basic`
- **Scheduler:** Slurm
- **Cluster:** DEAC
## Screenshots
<!-- TODO: Add a screenshot of MATLAB running in the browser session -->
## Features
- Launches MATLAB GUI in a web browser via `matlab-proxy-app` on compute nodes
using Batch Connect `basic` template
- Token-based authentication for secure sessions
- Auto-shutdown on idle (360 second timeout)
- Multiple MATLAB versions available (R2023b, R2024a)
- Configurable Slurm account, partition, node type, cores, memory, and GPUs
via the launch form
- Working directory selector
- Optional additional environment modules can be loaded at launch time
- Multiple CPU and GPU node types supported (AMD Zen3/Zen4, Intel Cascade
Lake/Skylake, A100, V100)
- Modules loaded at runtime: `apps/python/3.11.8` + selected MATLAB version
## Requirements
### Compute Node Software
- [MATLAB](https://www.mathworks.com/products/matlab.html) available as an
environment module (currently `apps/matlab/2023b` and `apps/matlab/2024a`)
- [matlab-proxy](https://github.com/mathworks/matlab-proxy) Python package
installed (provides `matlab-proxy-app`)
- Python 3 available as an environment module (currently `apps/python/3.11.8`)
- [Environment Modules](https://modules.readthedocs.io/) with init at
`/usr/share/Modules/init/bash`
- Valid MATLAB license accessible from compute nodes
### Open OnDemand
<!-- TODO: Specify the minimum OOD version this app has been tested with -->
- Slurm scheduler
## App Installation
### 1. Clone the repository
```sh
cd /var/www/ood/apps/sys
git clone https://github.com/WFU-HPC/OOD-apps.server.matlab.git
cd OOD-apps.server.matlab
```
### 2. Configure for your site
Edit `form.yml.erb` and update these values for your cluster:
| Attribute | WFU Default | Change to |
|-------------|----------------------------------------|------------------------------------|
| `cluster` | `"deac"` | Your cluster name |
| `version` | `"apps/matlab/2023b"`, `"apps/matlab/2024a"` | MATLAB module paths on your system |
| `accounts` | WFU Slurm accounts | Your Slurm accounts |
| `queues` | `"small"` | Your Slurm partitions |
| `node_type` | WFU-specific node types | Node types on your cluster |
You will also need to update `submit.yml.erb` if your cluster uses different
Slurm constraint names or node configurations.
In `script.sh.erb`, the app loads:
```
module load apps/python/3.11.8
module load apps/matlab/2024a
```
Ensure equivalent modules with `matlab-proxy` installed are available on
your system.
### 3. Verify
No OOD restart is needed (Batch Connect apps are detected automatically).
Visit your OOD dashboard and look for **MATLAB** under
**Interactive Apps > Math and Statistics**.
## Configuration
### form.yml.erb attributes
| Attribute | Widget | Description | Default |
|------------------------|-----------------|-----------------------------------------------|----------------------------|
| `version` | select | MATLAB version to load | `"apps/matlab/2023b"` |
| `enable_extra_modules` | check_box | Toggle extra module loading | unchecked |
| `extra_modules` | text_field | Additional environment modules to load | `""` |
| `working_dir` | path_selector | Working directory for the session | User's `$HOME` |
| `accounts` | select | Slurm account for job submission | (dynamic from cluster) |
| `queues` | select | Slurm partition | `"small"` |
| `bc_num_hours` | number | Maximum wall time (hours) | `1` |
| `num_cores` | number_field | Number of CPU cores | `1` |
| `memory` | number_field | Memory in GB | `8` |
| `node_type` | select | Compute node type (CPU, GPU, specific HW) | Any (shortest wait) |
| `num_gpus` | number_field | Number of GPUs (for GPU node types) | `0` |
## Troubleshooting
<!-- TODO: Add troubleshooting tips -->
## Testing
<!-- TODO: Update with sites where this app has been deployed -->
| Site | OOD Version | Scheduler | Status |
|-------------------------------|---------------|-----------|--------|
| Wake Forest University (DEAC) | <!-- TODO --> | Slurm | <!-- TODO --> |
## Known Limitations
<!-- TODO: Document any known limitations -->
## Contributing
Contributions are welcome. To contribute:
1. Fork this repository
2. Create a feature branch (`git checkout -b feature/my-improvement`)
3. Submit a pull request with a description of your changes
For bugs or feature requests,
[open an issue](https://github.com/WFU-HPC/OOD-apps.server.matlab/issues).
## References
- [MATLAB](https://www.mathworks.com/products/matlab.html) -- the computing
platform launched by this app
- [matlab-proxy](https://github.com/mathworks/matlab-proxy) -- the Python
package providing the web proxy server
- [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)
### Software Installation
<!-- TODO: Add notes about installing MATLAB and matlab-proxy on your compute nodes -->
## License
[MIT License](LICENSE)
## 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. Thanks for your contributions to the Open OnDemand community!