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
vnctemplate, Slurm scheduler, VirtualGL, CPU thread configuration, and link to the upstream VMD 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
# VMD App for Open OnDemand (OOD)
- Wake Forest University (WFU) HPC Team<br>
- Primary Contact: Sean Anderson (anderss@wfu.edu)<br>
-
- This is WFU's VMD app for DEAC OnDemand.
+ ## Overview
+
+ An [Open OnDemand](https://openondemand.org/) Batch Connect app that launches
+ [VMD](https://www.ks.uiuc.edu/Research/vmd/) as an interactive VNC desktop
+ session on HPC clusters. VMD is designed for modeling, visualization, and
+ analysis of biological systems such as proteins, nucleic acids, lipid bilayer
+ assemblies, etc. It may be used to view more general molecules, as VMD can read
+ standard Protein Data Bank (PDB) files and display the contained structure.
+
+ This app uses the Batch Connect `vnc` template with an Xfce desktop. The VNC
+ session is launched with VirtualGL (`-vgl` in `submit.yml.erb`), and the
+ script also sets `LIBGL_ALWAYS_SOFTWARE=1` for software rendering. VMD is
+ launched inside an `xfce4-terminal` with CPU thread counts configured from
+ `$SLURM_NTASKS`.
+
+ Developed by the Wake Forest University (WFU) HPC Team.
+ Primary Contact: Sean Anderson (anderss@wfu.edu)
+
+ - **Upstream project:** [VMD](https://www.ks.uiuc.edu/Research/vmd/)
+ - **Batch Connect template:** `vnc`
+ - **Scheduler:** Slurm
+ - **Cluster:** DEAC
+
+ ## Screenshots
+
+ <!-- TODO: Add a screenshot of VMD running in the VNC session -->
+
+ ## Features
+
+ - Launches VMD (`vmd`) via VNC desktop on compute nodes inside an
+ `xfce4-terminal`
+ - Xfce desktop environment with VirtualGL and software rendering
+ - CPU thread count automatically set from `$SLURM_NTASKS` via
+ `VMDFORCECPUCOUNT`, `WKFFORCECPUCOUNT`, and `RTFORCECPUCOUNT`
+ - 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)
+ - Module loaded at runtime: `apps/vmd/1.9.4a57`
+
+ ## Requirements
+
+ ### Compute Node Software
+
+ - [VMD](https://www.ks.uiuc.edu/Research/vmd/) available as an environment
+ module (currently `apps/vmd/1.9.4a57`)
+ - [Environment Modules](https://modules.readthedocs.io/) with init at
+ `/usr/share/Modules/init/bash`
+ - [Xfce Desktop](https://xfce.org/) (`xfwm4`, `xfce4-panel`, `xfsettingsd`,
+ `xfce4-terminal`)
+ - [VirtualGL](https://www.virtualgl.org/) (required -- the app passes `-vgl`
+ to the VNC session)
+ - A VNC server (e.g. [TurboVNC](https://www.turbovnc.org/))
+ - [websockify](https://github.com/novnc/websockify)
+ - D-Bus (`dbus-launch` is called in the script)
+
+ ### 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.vnc.vmd.git
+ cd OOD-apps.vnc.vmd
+ ```
+
+ ### 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/vmd/1.9.4a57"` | Module path on your system |
+ | `accounts` | WFU Slurm accounts | Your Slurm accounts |
+ | `queues` | `"ondemand"` | Your Slurm partition |
+ | `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 the module with:
+ ```
+ module load apps/vmd/1.9.4a57
+ ```
+ Ensure an equivalent module is available on your system.
+
+ ### 3. Verify
+
+ No OOD restart is needed (Batch Connect apps are detected automatically).
+ Visit your OOD dashboard and look for **VMD** under
+ **Interactive Apps > Physics, Biophysics, and Chemistry**.
+
+ ## Configuration
+
+ ### form.yml.erb attributes
+
+ | Attribute | Widget | Description | Default |
+ |--------------------|-----------------|-----------------------------------------------|----------------------------|
+ | `version` | select | VMD module to load | `"apps/vmd/1.9.4a57"` |
+ | `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 | `"ondemand"` |
+ | `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.vnc.vmd/issues).
+
+ ## References
+
+ - [VMD](https://www.ks.uiuc.edu/Research/vmd/) -- the molecular visualization
+ program 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)
+
+ ### Software Installation
+
+ <!-- TODO: Add notes about building or installing VMD on your compute nodes -->
+
+ ## License
+
+ [MIT License](LICENSE)
+
+ ## Acknowledgments
+
+ <!-- TODO: Add funding or institutional support information -->Clean README.md -- copy-paste ready
# VMD App for Open OnDemand (OOD)
## Overview
An [Open OnDemand](https://openondemand.org/) Batch Connect app that launches
[VMD](https://www.ks.uiuc.edu/Research/vmd/) as an interactive VNC desktop
session on HPC clusters. VMD is designed for modeling, visualization, and
analysis of biological systems such as proteins, nucleic acids, lipid bilayer
assemblies, etc. It may be used to view more general molecules, as VMD can read
standard Protein Data Bank (PDB) files and display the contained structure.
This app uses the Batch Connect `vnc` template with an Xfce desktop. The VNC
session is launched with VirtualGL (`-vgl` in `submit.yml.erb`), and the
script also sets `LIBGL_ALWAYS_SOFTWARE=1` for software rendering. VMD is
launched inside an `xfce4-terminal` with CPU thread counts configured from
`$SLURM_NTASKS`.
Developed by the Wake Forest University (WFU) HPC Team.
Primary Contact: Sean Anderson (anderss@wfu.edu)
- **Upstream project:** [VMD](https://www.ks.uiuc.edu/Research/vmd/)
- **Batch Connect template:** `vnc`
- **Scheduler:** Slurm
- **Cluster:** DEAC
## Screenshots
<!-- TODO: Add a screenshot of VMD running in the VNC session -->
## Features
- Launches VMD (`vmd`) via VNC desktop on compute nodes inside an
`xfce4-terminal`
- Xfce desktop environment with VirtualGL and software rendering
- CPU thread count automatically set from `$SLURM_NTASKS` via
`VMDFORCECPUCOUNT`, `WKFFORCECPUCOUNT`, and `RTFORCECPUCOUNT`
- 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)
- Module loaded at runtime: `apps/vmd/1.9.4a57`
## Requirements
### Compute Node Software
- [VMD](https://www.ks.uiuc.edu/Research/vmd/) available as an environment
module (currently `apps/vmd/1.9.4a57`)
- [Environment Modules](https://modules.readthedocs.io/) with init at
`/usr/share/Modules/init/bash`
- [Xfce Desktop](https://xfce.org/) (`xfwm4`, `xfce4-panel`, `xfsettingsd`,
`xfce4-terminal`)
- [VirtualGL](https://www.virtualgl.org/) (required -- the app passes `-vgl`
to the VNC session)
- A VNC server (e.g. [TurboVNC](https://www.turbovnc.org/))
- [websockify](https://github.com/novnc/websockify)
- D-Bus (`dbus-launch` is called in the script)
### 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.vnc.vmd.git
cd OOD-apps.vnc.vmd
```
### 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/vmd/1.9.4a57"` | Module path on your system |
| `accounts` | WFU Slurm accounts | Your Slurm accounts |
| `queues` | `"ondemand"` | Your Slurm partition |
| `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 the module with:
```
module load apps/vmd/1.9.4a57
```
Ensure an equivalent module is available on your system.
### 3. Verify
No OOD restart is needed (Batch Connect apps are detected automatically).
Visit your OOD dashboard and look for **VMD** under
**Interactive Apps > Physics, Biophysics, and Chemistry**.
## Configuration
### form.yml.erb attributes
| Attribute | Widget | Description | Default |
|--------------------|-----------------|-----------------------------------------------|----------------------------|
| `version` | select | VMD module to load | `"apps/vmd/1.9.4a57"` |
| `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 | `"ondemand"` |
| `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.vnc.vmd/issues).
## References
- [VMD](https://www.ks.uiuc.edu/Research/vmd/) -- the molecular visualization
program 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)
### Software Installation
<!-- TODO: Add notes about building or installing VMD 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!