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
- Prerequisites / Requirements
- App Installation (with release tag
v0.6.0 and site configuration guidance)
- Configuration (
form.yml attributes table)
- Troubleshooting
- Testing
- Known Limitations
- Contributing
- References
- License
- Acknowledgments
Sections that could be expanded:
- Overview -- currently a brief paragraph; could mention app type (Batch Connect
vnc template), supported clusters, and link to the upstream VisIt project
Sections already present:
- Overview (brief) -- mentions VisIt and links to the upstream project; notes this is OSC's production deployment
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
- # Visit Open-OnDemand application
+ # Batch Connect - OSC VisIt
+
+ 
+ [](https://opensource.org/licenses/MIT)
+
+ ## Overview
- This is OSC's production deployoment of the
- [Visit](https://visit-dav.github.io/visit-website/index.html) software
- as an Open OnDemand interactive application.
+ An [Open OnDemand](https://openondemand.org/) Batch Connect app that launches
+ a [VisIt](https://visit-dav.github.io/visit-website/index.html) GUI in an
+ XFCE desktop session on OSC HPC clusters. VisIt is an open-source,
+ interactive, scalable visualization, animation, and analysis tool for
+ scientific data.
- As this is the OSC's production application, anyone outside of OSC should/can
- fork this repo and modify it as needed.
+ This app uses the Batch Connect `vnc` template with Slurm and supports
+ clusters: Pitzer, Cardinal, and Ascend.
+
+ - **Upstream project:** [VisIt](https://visit-dav.github.io/visit-website/index.html)
+ - **Batch Connect template:** `vnc`
+ - **Scheduler:** Slurm
+
+ ## Screenshots
+
+ <!-- TODO: Add a screenshot of the app's launch form or a running session -->
+
+ ## Features
+
+ - Launches VisIt GUI (`visit -small`) in an XFCE VNC desktop session
+ - Multi-cluster support (Pitzer, Cardinal, Ascend)
+ - VisIt version selectable via the `auto_modules_visit` form attribute
+ - Configurable cores and wall time via the launch form
+ - Dynamic max core count based on selected cluster (48 for Pitzer, 96 for
+ Cardinal, 118 for Ascend)
+
+ ## 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):
+
+ - [VisIt](https://visit-dav.github.io/visit-website/index.html)
+ - [Xfce Desktop](https://xfce.org/) 4+
+ - [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
+
+ For VNC server support:
+
+ - [TurboVNC](http://www.turbovnc.org/) 2.1+
+ - [websockify](https://github.com/novnc/websockify) 0.8.0+
+
+ ### 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/OSC/bc_osc_visit.git
+ cd bc_osc_visit
+
+ # Pin to a release (recommended)
+ git checkout v0.6.0
+ ```
+
+ 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`, `ascend` | Your cluster name(s) |
+ | `auto_modules_visit` | (auto-populated by OOD) | VisIt module available on your system |
+ | `cores.max` | `28` | Max cores on your compute nodes |
+
+ In `script.sh.erb`, the app loads the VisIt module with:
+ ```
+ module load <auto_modules_visit>
+ ```
+ Ensure an equivalent VisIt module is available on your system.
+
+ ### 3. Update the app
+
+ ```sh
+ cd /var/www/ood/apps/sys/bc_osc_visit
+ 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`, `ascend` |
+ | `auto_modules_visit` | select | VisIt module to load (auto-populated by OOD) | (auto) |
+ | `bc_num_hours` | number | Maximum wall time (hours) | <!-- TODO: specify default --> |
+ | `cores` | number_field | Number of CPU cores (1--28, max varies by cluster) | `1` |
+
+ ## 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 -->
+
+ ## Contributing
+
+ 1. Fork it ( https://github.com/OSC/bc_osc_visit/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_visit/issues).
+
+ ## References
+
+ - [VisIt](https://visit-dav.github.io/visit-website/index.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)
+
+ ## License
+
+ <!-- TODO: Specify the license for this project -->
+
+ ## Acknowledgments
+
+ <!-- TODO: Add funding or institutional support information -->
Clean README.md -- copy-paste ready
# Batch Connect - OSC VisIt
[](https://opensource.org/licenses/MIT)
## Overview
An [Open OnDemand](https://openondemand.org/) Batch Connect app that launches
a [VisIt](https://visit-dav.github.io/visit-website/index.html) GUI in an
XFCE desktop session on OSC HPC clusters. VisIt is an open-source,
interactive, scalable visualization, animation, and analysis tool for
scientific data.
This app uses the Batch Connect `vnc` template with Slurm and supports
clusters: Pitzer, Cardinal, and Ascend.
- **Upstream project:** [VisIt](https://visit-dav.github.io/visit-website/index.html)
- **Batch Connect template:** `vnc`
- **Scheduler:** Slurm
## Screenshots
<!-- TODO: Add a screenshot of the app's launch form or a running session -->
## Features
- Launches VisIt GUI (`visit -small`) in an XFCE VNC desktop session
- Multi-cluster support (Pitzer, Cardinal, Ascend)
- VisIt version selectable via the `auto_modules_visit` form attribute
- Configurable cores and wall time via the launch form
- Dynamic max core count based on selected cluster (48 for Pitzer, 96 for
Cardinal, 118 for Ascend)
## 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):
- [VisIt](https://visit-dav.github.io/visit-website/index.html)
- [Xfce Desktop](https://xfce.org/) 4+
- [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
For VNC server support:
- [TurboVNC](http://www.turbovnc.org/) 2.1+
- [websockify](https://github.com/novnc/websockify) 0.8.0+
### 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/OSC/bc_osc_visit.git
cd bc_osc_visit
# Pin to a release (recommended)
git checkout v0.6.0
```
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`, `ascend` | Your cluster name(s) |
| `auto_modules_visit` | (auto-populated by OOD) | VisIt module available on your system |
| `cores.max` | `28` | Max cores on your compute nodes |
In `script.sh.erb`, the app loads the VisIt module with:
```
module load <auto_modules_visit>
```
Ensure an equivalent VisIt module is available on your system.
### 3. Update the app
```sh
cd /var/www/ood/apps/sys/bc_osc_visit
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`, `ascend` |
| `auto_modules_visit` | select | VisIt module to load (auto-populated by OOD) | (auto) |
| `bc_num_hours` | number | Maximum wall time (hours) | <!-- TODO: specify default --> |
| `cores` | number_field | Number of CPU cores (1--28, max varies by cluster) | `1` |
## 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 -->
## Contributing
1. Fork it ( https://github.com/OSC/bc_osc_visit/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_visit/issues).
## References
- [VisIt](https://visit-dav.github.io/visit-website/index.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)
## License
<!-- TODO: Specify the license for this project -->
## 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):
v0.6.0and site configuration guidance)form.ymlattributes table)Sections that could be expanded:
vnctemplate), supported clusters, and link to the upstream VisIt projectSections 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.