# Batch Connect - OSC RStudio Server
[](https://opensource.org/licenses/MIT)
## Overview
An [Open OnDemand](https://openondemand.org/) Batch Connect app that launches
an [RStudio Server](https://www.rstudio.com/products/rstudio-server/) session
for [R](https://www.r-project.org/) on OSC HPC clusters. RStudio Server
provides a web-based IDE for R with code editing, debugging, and visualization
capabilities.
This app uses the Batch Connect `basic` template with Slurm and supports
clusters: Pitzer, Ascend, Cardinal, and Kubernetes.
- **Upstream project:** [RStudio Server](https://www.rstudio.com/products/rstudio-server/)
- **Batch Connect template:** `basic`
- **Scheduler:** Slurm
## Screenshots
<!-- TODO: Add a screenshot of the app's launch form or a running session -->
## Features
- Multi-cluster support (Pitzer, Ascend, Cardinal, Kubernetes)
- Multiple R versions available (4.4.0, 4.3.0, 4.2.1, 4.1.0, 4.0.2, 3.6.3)
via `app_rstudio_server/` and `R/` modules
- GPU-enabled node types
- Configurable cores, wall time, and node type (standard, 40-core, 48-core,
GPU, hugemem, largemem, debug) via the launch form
- Kubernetes container support with Docker image
- Module-based software loading via Lmod (`project/ondemand`,
`rstudio_launcher/centos7`, `app_rstudio_server/` or `R/`)
- CSRF token support for RStudio 1.4+
- Bubblewrap (`bwrap`) isolation for non-Kubernetes clusters
## 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 restore` and `module load <modules>` based CLI
- [R](https://www.r-project.org/) 3.3.2+ (earlier versions are untested but
may work)
- [RStudio Server](https://www.rstudio.com/products/rstudio-server/) 1.0.136+
- [Bubblewrap](https://github.com/containers/bubblewrap) (`bwrap`) for
non-Kubernetes clusters
### Open OnDemand
<!-- TODO: Specify the minimum OOD version this app has been tested with -->
- Slurm scheduler
### Optional
- [Singularity](https://sylabs.io/singularity/) 2.4.2+ (alternative to
bubblewrap -- see [nickjer/singularity-rstudio](https://www.singularity-hub.org/collections/463))
## App Installation
### 1. Clone the repository
```sh
cd /var/www/ood/apps/sys
git clone https://github.com/OSC/bc_osc_rstudio_server.git
cd bc_osc_rstudio_server
# Pin to a release (recommended)
git checkout v0.33.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`, `ascend`, `cardinal`, etc. | Your cluster name(s) |
| `version` | `gcc/12.3.0 R/4.4.0` (and others) | Module load strings for R versions available 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 project/ondemand
module load rstudio_launcher/centos7
module load <version>
```
Ensure equivalent modules are available on your system.
### 3. Update the app
```sh
cd /var/www/ood/apps/sys/bc_osc_rstudio_server
git fetch
git checkout <tag>
```
No restart is needed.
## Configuration
### form.yml attributes
| Attribute | Widget | Description | Default |
|---------------|--------------|----------------------------------------------------------|---------|
| `cluster` | select | Target cluster ID(s) | `pitzer`, `ascend`, `cardinal`, `kubernetes`, `kubernetes-test`, `kubernetes-dev` |
| `version` | select | R version / module load string | `gcc/12.3.0 R/4.4.0` |
| `bc_num_hours`| number | Maximum wall time (hours) | <!-- TODO: specify default --> |
| `node_type` | select | Compute node type (any, 40 core, 48 core, GPU, hugemem, largemem, debug) | `any` |
| `num_cores` | number_field | Number of CPU cores (1--28, varies by node type/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_rstudio_server/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_rstudio_server/issues).
## References
- [RStudio Server](https://www.rstudio.com/products/rstudio-server/) -- the
application launched by this app
- [R](https://www.r-project.org/) -- the underlying language
- [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_rstudio_server/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)
* RStudio, Shiny and the RStudio logo are all registered trademarks of RStudio.
## Acknowledgments
<!-- TODO: Add funding or institutional support information -->
## RServer command line arguments
This was the output of `--help` from version `2021.09.1`.
```
command-line options:
verify:
--verify-installation arg (=0) Runs verification mode to verify the
current installation.
server:
--server-working-dir arg (=/) The default working directory of the
rserver process.
--server-user arg (=rstudio-server) The user account of the rserver
process.
--server-daemonize arg (=0) Indicates whether or not the rserver
process should run as a daemon.
...
```
(See existing README for full command-line reference.)
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:
v0.33.0), addform.ymlconfiguration guidance for deployers at other sites, and include site-specific customization stepsSections 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.