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), Singularity container usage, and link to the upstream QGIS project
- Install -- could use the latest release tag (
v0.8.0), add form.yml configuration guidance for deployers at other sites, and include site-specific customization steps (especially the Singularity container and OSC_QGIS_DIR setup)
- Prerequisites -- could add Open OnDemand version, VNC server requirements, and note that the QGIS module must set the
OSC_QGIS_DIR environment variable pointing to the Singularity image
Sections already present:
- Prerequisites (compute node software) -- lists Lmod, Xfce, and the
OSC/sa_singularity_qgis Singularity container
- 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 QGIS
[](https://opensource.org/licenses/MIT)
- An interactive app designed for OSC OnDemand that launches QGIS within an Owens batch job.
+ ## Overview
+
+ An [Open OnDemand](https://openondemand.org/) Batch Connect app that launches
+ [QGIS](https://qgis.org/) via VNC in an Xfce desktop session on the OSC Pitzer
+ cluster. QGIS is a free and open-source geographic information system for
+ creating, editing, visualizing, analyzing, and publishing geospatial
+ information. This app runs QGIS inside a Singularity container.
+
+ This app uses the Batch Connect `vnc` template with Slurm and supports
+ cluster: Pitzer.
+
+ - **Upstream project:** [QGIS](https://qgis.org/)
+ - **Batch Connect template:** `vnc`
+ - **Scheduler:** Slurm
+
+ ## Screenshots
+
+ <!-- TODO: Add a screenshot of the app's launch form or a running session -->
+
+ ## Features
+
+ - Launches QGIS in a VNC desktop session with Xfce window manager
+ - Runs inside a Singularity container (`qgis.sif`) for reproducibility
+ - Multiple node types: standard compute (48 core), GPU, largemem, hugemem, debug
+ - Configurable core count (1--28, 4 GB of RAM per core)
+ - Multiple QGIS versions available via the `qgis/` module (auto-detected)
+ - 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):
- - [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 before
launching the container.
- - [XFCE] is used to provide the window manager and terminal access if desired
- - [OSC/sa_singularity_qgis] which provides [QGIS] version 3.4.12
+ - [Xfce](https://www.xfce.org/) is used to provide the window manager and
+ terminal access if desired
+ - [Singularity](https://sylabs.io/singularity/) container runtime
+ - A QGIS Singularity image (see
+ [OSC/sa_singularity_qgis](https://github.com/OSC/sa_singularity_qgis))
+ - The QGIS module must set the `OSC_QGIS_DIR` environment variable pointing
+ to the directory containing `qgis.sif`
- [Lmod]: https://www.tacc.utexas.edu/research-development/tacc-projects/lmod
- [QGIS]: https://qgis.org/en/site/
- [OSC/sa_singularity_qgis]: https://github.com/OSC/sa_singularity_qgis
- [XFCE]: https://www.xfce.org/
+ For VNC server support:
+
+ - A VNC server (e.g., [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
+ - Batch Connect VNC template support
- ## 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 rh-git29 -- git clone <repo>
- cd <dir>
- scl enable rh-git29 -- git checkout <tag/branch>
+ cd /var/www/ood/apps/sys
+ git clone https://github.com/OSC/bc_osc_qgis.git
+ cd bc_osc_qgis
+
+ # Pin to a release (recommended)
+ git checkout v0.8.0
```
- 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 rh-git29 -- git fetch
- scl enable rh-git29 -- 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` | Your cluster name(s) |
+ | `auto_modules_qgis`| auto-detected | QGIS 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 the QGIS module and launches:
+ ```
+ module load <qgis_module>
+ singularity run $OSC_QGIS_DIR/qgis.sif
+ ```
+ Your QGIS module must set `OSC_QGIS_DIR` to the directory containing your
+ `qgis.sif` Singularity image. You can build this image using
+ [OSC/sa_singularity_qgis](https://github.com/OSC/sa_singularity_qgis) or
+ provide your own.
+
+ ### 3. Update the app
+
+ ```sh
+ cd /var/www/ood/apps/sys/bc_osc_qgis
+ 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` |
+ | `auto_modules_qgis`| auto-select | QGIS 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, 4 GB RAM per core) | `1` |
+ | `node_type` | select | Compute node type (any, 48 core, any 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_qgis/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_qgis/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
+
+ - [QGIS](https://qgis.org/) -- the application launched by this app
+ - [OSC/sa_singularity_qgis](https://github.com/OSC/sa_singularity_qgis) -- Singularity container build recipe for QGIS
+ - [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_qgis/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)o
+ * Code is licensed under MIT (see LICENSE.txt)
* The QGIS name and logo are protected under European law.
+ ## Acknowledgments
+
+ <!-- TODO: Add funding or institutional support information -->
Clean README.md -- copy-paste ready
# Batch Connect - OSC QGIS
[](https://opensource.org/licenses/MIT)
## Overview
An [Open OnDemand](https://openondemand.org/) Batch Connect app that launches
[QGIS](https://qgis.org/) via VNC in an Xfce desktop session on the OSC Pitzer
cluster. QGIS is a free and open-source geographic information system for
creating, editing, visualizing, analyzing, and publishing geospatial
information. This app runs QGIS inside a Singularity container.
This app uses the Batch Connect `vnc` template with Slurm and supports
cluster: Pitzer.
- **Upstream project:** [QGIS](https://qgis.org/)
- **Batch Connect template:** `vnc`
- **Scheduler:** Slurm
## Screenshots
<!-- TODO: Add a screenshot of the app's launch form or a running session -->
## Features
- Launches QGIS in a VNC desktop session with Xfce window manager
- Runs inside a Singularity container (`qgis.sif`) for reproducibility
- Multiple node types: standard compute (48 core), GPU, largemem, hugemem, debug
- Configurable core count (1--28, 4 GB of RAM per core)
- Multiple QGIS versions available via the `qgis/` module (auto-detected)
- 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):
- [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 before
launching the container.
- [Xfce](https://www.xfce.org/) is used to provide the window manager and
terminal access if desired
- [Singularity](https://sylabs.io/singularity/) container runtime
- A QGIS Singularity image (see
[OSC/sa_singularity_qgis](https://github.com/OSC/sa_singularity_qgis))
- The QGIS module must set the `OSC_QGIS_DIR` environment variable pointing
to the directory containing `qgis.sif`
For VNC server support:
- A VNC server (e.g., [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
- Batch Connect VNC template support
## App Installation
### 1. Clone the repository
```sh
cd /var/www/ood/apps/sys
git clone https://github.com/OSC/bc_osc_qgis.git
cd bc_osc_qgis
# Pin to a release (recommended)
git checkout v0.8.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` | Your cluster name(s) |
| `auto_modules_qgis`| auto-detected | QGIS 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 the QGIS module and launches:
```
module load <qgis_module>
singularity run $OSC_QGIS_DIR/qgis.sif
```
Your QGIS module must set `OSC_QGIS_DIR` to the directory containing your
`qgis.sif` Singularity image. You can build this image using
[OSC/sa_singularity_qgis](https://github.com/OSC/sa_singularity_qgis) or
provide your own.
### 3. Update the app
```sh
cd /var/www/ood/apps/sys/bc_osc_qgis
git fetch
git checkout <tag>
```
No restart is needed.
## Configuration
### form.yml attributes
| Attribute | Widget | Description | Default |
|--------------------|--------------|-------------------------------------------------------|-----------|
| `cluster` | select | Target cluster ID(s) | `pitzer` |
| `auto_modules_qgis`| auto-select | QGIS 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, 4 GB RAM per core) | `1` |
| `node_type` | select | Compute node type (any, 48 core, any 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_qgis/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_qgis/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
- [QGIS](https://qgis.org/) -- the application launched by this app
- [OSC/sa_singularity_qgis](https://github.com/OSC/sa_singularity_qgis) -- Singularity container build recipe for QGIS
- [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_qgis/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)
* The QGIS name and logo are protected under European law.
## 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), Singularity container usage, and link to the upstream QGIS projectv0.8.0), addform.ymlconfiguration guidance for deployers at other sites, and include site-specific customization steps (especially the Singularity container andOSC_QGIS_DIRsetup)OSC_QGIS_DIRenvironment variable pointing to the Singularity imageSections already present:
OSC/sa_singularity_qgisSingularity containerBelow 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.