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
- References
- License
- Acknowledgments
Sections that could be expanded:
- Overview -- could mention app type (Batch Connect
basic template), multi-cluster support (Ascend, Pitzer), working directory selector, and link to the upstream Code Server and VS Code projects
- Install -- could use the latest release tag (
v0.13.0), update the code-server binary deployment instructions to reflect current module-based loading via app_code_server/, and add a form.yml configuration table for deployers at other sites
- Prerequisites -- could add Open OnDemand version and organize into compute node vs. OOD requirements
- Known Issues -- could be renamed to Known Limitations for consistency
Sections already present:
- Prerequisites (compute node software) -- documented with Lmod and Code Server versions
- Install -- includes detailed binary deployment and configuration steps
- Update -- separate update section
- Known Issues -- documents extension installation and authentication limitations
- Contributing -- standard fork-and-PR workflow
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 Code Server
[](https://opensource.org/licenses/MIT)
- An improved file viewer / editor for OSC OnDemand that launches a
- Code Server within an Owens batch job. Code Server leverages VSCode as its
- editor.
+ ## Overview
+
+ An [Open OnDemand](https://openondemand.org/) Batch Connect app that launches
+ [Code Server](https://coder.com/) as an interactive web-based session on OSC
+ HPC clusters. Code Server provides a full
+ [VS Code](https://code.visualstudio.com/) editing experience running on a
+ compute node and accessible through a browser.
+
+ This app uses the Batch Connect `basic` template with Slurm and supports
+ clusters: Ascend and Pitzer.
+
+ - **Upstream project:** [Code Server](https://coder.com/) / [VS Code](https://code.visualstudio.com/)
+ - **Batch Connect template:** `basic`
+ - **Scheduler:** Slurm
+
+ ## Screenshots
+
+ <!-- TODO: Add a screenshot of the app's launch form or a running session -->
+
+ ## Features
+
+ - Full VS Code editor experience in the browser via Code Server
+ - Multi-cluster support (Ascend, Pitzer)
+ - Working directory selector for the Code Server session
+ - Dynamic Code Server module selection via `auto_modules_app_code_server`
+ - Password-authenticated sessions
+ - C/C++ extension support with IntelliSense database on local filesystem
+ - Telemetry disabled by default
+ - Module-based software loading via Lmod (`project/ondemand`, `app_code_server/`)
- ## 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
- CLI used to load appropriate environments within the batch job before
- launching Code server.
- - [Code Server] 2.x+ available from Github: https://github.com/cdr/code-server/releases
+ - [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
+ Code Server
+ - [Code Server](https://coder.com/) 2.x+ available from GitHub:
+ https://github.com/coder/code-server/releases
- [Code Server]: https://coder.com/
- [Lmod]: https://www.tacc.utexas.edu/research-development/tacc-projects/lmod
- [VS Code]: https://code.visualstudio.com/
+ ### Open OnDemand
- ## Install
+ <!-- TODO: Specify the minimum OOD version this app has been tested with -->
+ - Slurm scheduler
- 1. Use Git to clone this app and checkout the desired branch/version you want to
- use and place this wherever you store batch connect apps (`/var/www/ood/apps/sys` or `~/ondemand/dev`):
+ ## App Installation
+
+ ### 1. Clone the repository
- ```sh
- scl enable git29 -- git clone <repo>
- cd <dir>
- scl enable git29 -- git checkout <tag/branch>
- ```
+ ```sh
+ cd /var/www/ood/apps/sys
+ git clone https://github.com/OSC/bc_osc_codeserver.git
+ cd bc_osc_codeserver
+
+ # Pin to a release (recommended)
+ git checkout v0.13.0
+ ```
- 2. Deploy code-server on your systems.
+ No restart is needed -- Batch Connect apps are not Passenger apps and are
+ detected automatically.
+
+ ### 2. Deploy Code Server binary
- ```sh
- # replace URL with latest release from code-server
- wget https://github.com/cdr/code-server/releases/download/3.2.0/code-server-3.2.0-linux-x86_64.tar.gz
- tar -xzf code-server-3.2.0-linux-x86_64.tar.gz
- ```
+ If you are not using the `app_code_server/` module, you can deploy the
+ code-server binary manually:
+
+ ```sh
+ # Replace URL with latest release from code-server
+ wget https://github.com/coder/code-server/releases/download/<version>/code-server-<version>-linux-amd64.tar.gz
+ tar -xzf code-server-<version>-linux-amd64.tar.gz
+ ```
- 3. You will notice code-server is an executable inside that directory and can get the full path:
-
- ```sh
- $ readlink -f code-server-3.2.0-linux-x86_64.tar.gz
- /users/PZS0562/efranz/code-server-3.2.0-linux-x86_64.tar.gz
- ```
-
- 4. Update the path to the code-server binary in the script https://github.com/OSC/bc_osc_codeserver/blob/3082790ee69c82fe6fe757074da7d8d18c7d7e3d/template/script.sh.erb#L27:
-
- ```diff
- # An arbitrary path...
- - /fs/project/PZS0714/mrodgers/bin/code-server-2.1523-vsc1.38.1 \
- + /users/PZS0562/efranz/code-server-3.2.0-linux-x86_64/code-server \
- --auth=password \
- --port="$port" \
- ```
-
- 5. Update form.yml to use the correct cluster, and any other changes as necessary to form.yml or submit.yml that is appropriate for your cluster.
+ ### 3. Configure for your site
+
+ Edit `form.yml` and update these values for your cluster:
+
+ | Attribute | OSC Default | Change to |
+ |--------------------------------|----------------------|----------------------------------|
+ | `cluster` | `ascend`, `pitzer` | Your cluster name(s) |
+ | `auto_modules_app_code_server` | (dynamic) | Code Server module name(s) on your system |
+
+ In `script.sh.erb`, the app loads modules with:
+ ```
+ module load project/ondemand app_code_server/<version>
+ ```
+ Ensure equivalent modules are available on your system, or update the script
+ to point to your code-server binary path.
- ## Update
+ ### 4. Update the app
- To update the app you would:
-
```sh
- cd <dir>
- scl enable git29 -- git fetch
- scl enable git29 -- git checkout <tag/branch>
+ cd /var/www/ood/apps/sys/bc_osc_codeserver
+ 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) | `ascend`, `pitzer` |
+ | `bc_num_hours` | number | Maximum wall time (hours) | <!-- TODO: specify default --> |
+ | `working_dir` | path_selector | Working directory for the Code Server session | `$HOME` |
+ | `auto_modules_app_code_server` | select | Code Server module version to load (auto-detected) | (dynamic) |
- ## Known Issues
+ ## Known Limitations
- In-app installation of extensions does not work
- The authentication provided by code-server is unencrypted
+ <!-- TODO: Document any additional known limitations -->
+
+ ## 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 |
## Contributing
1. Fork it ( https://github.com/OSC/bc_osc_codeserver/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_codeserver/issues).
+
+ ## References
+
+ - [Code Server](https://coder.com/) -- the application launched by this app
+ - [VS Code](https://code.visualstudio.com/) -- the editor Code Server is based on
+ - [code-server GitHub releases](https://github.com/coder/code-server/releases)
+ -- binary releases of Code 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)
+ - [Changelog](https://github.com/OSC/bc_osc_codeserver/blob/master/CHANGELOG.md)
+ -- release history for this app
+
+ ## License
+
+ <!-- TODO: Add license information -->
+
+ ## Acknowledgments
+
+ <!-- TODO: Add funding or institutional support information -->
Clean README.md -- copy-paste ready
# Batch Connect - OSC Code Server
[](https://opensource.org/licenses/MIT)
## Overview
An [Open OnDemand](https://openondemand.org/) Batch Connect app that launches
[Code Server](https://coder.com/) as an interactive web-based session on OSC
HPC clusters. Code Server provides a full
[VS Code](https://code.visualstudio.com/) editing experience running on a
compute node and accessible through a browser.
This app uses the Batch Connect `basic` template with Slurm and supports
clusters: Ascend and Pitzer.
- **Upstream project:** [Code Server](https://coder.com/) / [VS Code](https://code.visualstudio.com/)
- **Batch Connect template:** `basic`
- **Scheduler:** Slurm
## Screenshots
<!-- TODO: Add a screenshot of the app's launch form or a running session -->
## Features
- Full VS Code editor experience in the browser via Code Server
- Multi-cluster support (Ascend, Pitzer)
- Working directory selector for the Code Server session
- Dynamic Code Server module selection via `auto_modules_app_code_server`
- Password-authenticated sessions
- C/C++ extension support with IntelliSense database on local filesystem
- Telemetry disabled by default
- Module-based software loading via Lmod (`project/ondemand`, `app_code_server/`)
## 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
Code Server
- [Code Server](https://coder.com/) 2.x+ available from GitHub:
https://github.com/coder/code-server/releases
### 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_codeserver.git
cd bc_osc_codeserver
# Pin to a release (recommended)
git checkout v0.13.0
```
No restart is needed -- Batch Connect apps are not Passenger apps and are
detected automatically.
### 2. Deploy Code Server binary
If you are not using the `app_code_server/` module, you can deploy the
code-server binary manually:
```sh
# Replace URL with latest release from code-server
wget https://github.com/coder/code-server/releases/download/<version>/code-server-<version>-linux-amd64.tar.gz
tar -xzf code-server-<version>-linux-amd64.tar.gz
```
### 3. Configure for your site
Edit `form.yml` and update these values for your cluster:
| Attribute | OSC Default | Change to |
|--------------------------------|----------------------|----------------------------------|
| `cluster` | `ascend`, `pitzer` | Your cluster name(s) |
| `auto_modules_app_code_server` | (dynamic) | Code Server module name(s) on your system |
In `script.sh.erb`, the app loads modules with:
```
module load project/ondemand app_code_server/<version>
```
Ensure equivalent modules are available on your system, or update the script
to point to your code-server binary path.
### 4. Update the app
```sh
cd /var/www/ood/apps/sys/bc_osc_codeserver
git fetch
git checkout <tag>
```
No restart is needed.
## Configuration
### form.yml attributes
| Attribute | Widget | Description | Default |
|--------------------------------|---------------|------------------------------------------------|------------------|
| `cluster` | select | Target cluster ID(s) | `ascend`, `pitzer` |
| `bc_num_hours` | number | Maximum wall time (hours) | <!-- TODO: specify default --> |
| `working_dir` | path_selector | Working directory for the Code Server session | `$HOME` |
| `auto_modules_app_code_server` | select | Code Server module version to load (auto-detected) | (dynamic) |
## Known Limitations
- In-app installation of extensions does not work
- The authentication provided by code-server is unencrypted
<!-- TODO: Document any additional known limitations -->
## 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 |
## Contributing
1. Fork it ( https://github.com/OSC/bc_osc_codeserver/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_codeserver/issues).
## References
- [Code Server](https://coder.com/) -- the application launched by this app
- [VS Code](https://code.visualstudio.com/) -- the editor Code Server is based on
- [code-server GitHub releases](https://github.com/coder/code-server/releases)
-- binary releases of Code 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)
- [Changelog](https://github.com/OSC/bc_osc_codeserver/blob/master/CHANGELOG.md)
-- release history for this app
## License
<!-- TODO: Add license information -->
## 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, you can create an ACCESS account and join the Appverse Affinity Group on the OnDemand Community Hub.
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:
basictemplate), multi-cluster support (Ascend, Pitzer), working directory selector, and link to the upstream Code Server and VS Code projectsv0.13.0), update thecode-serverbinary deployment instructions to reflect current module-based loading viaapp_code_server/, and add aform.ymlconfiguration table for deployers at other sitesSections 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, you can create an ACCESS account and join the Appverse Affinity Group on the OnDemand Community Hub.