Skip to content

Improve README to match Appverse documentation standard #1

Open
Open
Improve README to match Appverse documentation standard#1
@a-pasquale

Description

@a-pasquale
a-pasquale
opened on Feb 24, 2026

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.erb attributes table)
  • Troubleshooting
  • Testing
  • Known Limitations
  • Contributing
  • References
  • Acknowledgments

Sections that could be expanded:

  • Title and description -- could mention the Batch Connect basic template, Slurm scheduler, and link to the upstream CloudBeaver 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 
  # CloudBeaver App for Open OnDemand (OOD)

- Wake Forest University (WFU) HPC Team<br>
- Primary Contact: Sean Anderson (anderss@wfu.edu)<br>
-
- This is WFU's CloudBeaver app for DEAC OnDemand.
+ ## Overview
+
+ An [Open OnDemand](https://openondemand.org/) Batch Connect app that launches
+ [CloudBeaver](https://cloudbeaver.io/) as an interactive web server session on
+ HPC clusters. CloudBeaver is a lightweight web application designed for
+ efficient and secure data management, supporting SQL, NoSQL, and cloud
+ databases through a web browser.
+
+ This app uses the Batch Connect `basic` template to run CloudBeaver as a
+ reverse-proxied web server on a compute node. A `before.sh.erb` script handles
+ workspace initialization, port selection, and admin credential generation.
+
+ Developed by the Wake Forest University (WFU) HPC Team.
+ Primary Contact: Sean Anderson (anderss@wfu.edu)
+
+ - **Upstream project:** [CloudBeaver](https://cloudbeaver.io/)
+ - **Batch Connect template:** `basic`
+ - **Scheduler:** Slurm
+ - **Cluster:** DEAC
+
+ ## Screenshots
+
+ <!-- TODO: Add a screenshot of CloudBeaver running in the browser session -->
+
+ ## Features
+
+ - Launches CloudBeaver web server on compute nodes via Batch Connect `basic`
+   template
+ - Supports SQL, NoSQL, and cloud databases (DuckDB, H2, SQLite, PostgreSQL
+   enabled by default)
+ - Persistent workspace and configuration stored in
+   `~/.local/share/cloudbeaver/`
+ - Automatic admin user creation with generated password on first launch
+ - 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/cloudbeaver/25.0.4`
+
+ ## Requirements
+
+ ### Compute Node Software
+
+ - [CloudBeaver](https://cloudbeaver.io/) available as an environment module
+   (currently `apps/cloudbeaver/25.0.4`)
+ - [Environment Modules](https://modules.readthedocs.io/) with init at
+   `/usr/share/Modules/init/bash`
+ - Java runtime (CloudBeaver is a Java-based application)
+ - OpenSSL (used for password generation)
+
+ ### 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.server.cloudbeaver.git
+ cd OOD-apps.server.cloudbeaver
+ ```
+
+ ### 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/cloudbeaver/25.0.4"`       | 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 `before.sh.erb`, the runtime configuration references
+ `login.deac.wfu.edu` as the server URL -- update this for your site.
+
+ In `script.sh.erb`, the app loads the module with:
+ ```
+ module load apps/cloudbeaver/25.0.4
+ ```
+ 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 **CloudBeaver** under
+ **Interactive Apps > Database Development**.
+
+ ## Configuration
+
+ ### form.yml.erb attributes
+
+ | Attribute              | Widget          | Description                                   | Default                         |
+ |------------------------|-----------------|-----------------------------------------------|---------------------------------|
+ | `version`              | select          | CloudBeaver module to load                    | `"apps/cloudbeaver/25.0.4"`    |
+ | `enable_extra_modules` | check_box       | Toggle extra module loading                   | unchecked                       |
+ | `extra_modules`        | text_field      | Additional environment modules to load        | `""`                            |
+ | `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                           | `2`                             |
+ | `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.server.cloudbeaver/issues).
+
+ ## References
+
+ - [CloudBeaver](https://cloudbeaver.io/) -- the database management tool
+   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 CloudBeaver on your compute nodes -->
+
+ ## License
+
+ [MIT License](LICENSE)
+
+ ## Acknowledgments
+
+ <!-- TODO: Add funding or institutional support information -->
Clean README.md -- copy-paste ready 
# CloudBeaver App for Open OnDemand (OOD)

## Overview

An [Open OnDemand](https://openondemand.org/) Batch Connect app that launches
[CloudBeaver](https://cloudbeaver.io/) as an interactive web server session on
HPC clusters. CloudBeaver is a lightweight web application designed for
efficient and secure data management, supporting SQL, NoSQL, and cloud
databases through a web browser.

This app uses the Batch Connect `basic` template to run CloudBeaver as a
reverse-proxied web server on a compute node. A `before.sh.erb` script handles
workspace initialization, port selection, and admin credential generation.

Developed by the Wake Forest University (WFU) HPC Team.
Primary Contact: Sean Anderson (anderss@wfu.edu)

- **Upstream project:** [CloudBeaver](https://cloudbeaver.io/)
- **Batch Connect template:** `basic`
- **Scheduler:** Slurm
- **Cluster:** DEAC

## Screenshots

<!-- TODO: Add a screenshot of CloudBeaver running in the browser session -->

## Features

- Launches CloudBeaver web server on compute nodes via Batch Connect `basic`
  template
- Supports SQL, NoSQL, and cloud databases (DuckDB, H2, SQLite, PostgreSQL
  enabled by default)
- Persistent workspace and configuration stored in
  `~/.local/share/cloudbeaver/`
- Automatic admin user creation with generated password on first launch
- 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/cloudbeaver/25.0.4`

## Requirements

### Compute Node Software

- [CloudBeaver](https://cloudbeaver.io/) available as an environment module
  (currently `apps/cloudbeaver/25.0.4`)
- [Environment Modules](https://modules.readthedocs.io/) with init at
  `/usr/share/Modules/init/bash`
- Java runtime (CloudBeaver is a Java-based application)
- OpenSSL (used for password generation)

### 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.server.cloudbeaver.git
cd OOD-apps.server.cloudbeaver
```

### 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/cloudbeaver/25.0.4"`       | 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 `before.sh.erb`, the runtime configuration references
`login.deac.wfu.edu` as the server URL -- update this for your site.

In `script.sh.erb`, the app loads the module with:
```
module load apps/cloudbeaver/25.0.4
```
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 **CloudBeaver** under
**Interactive Apps > Database Development**.

## Configuration

### form.yml.erb attributes

| Attribute              | Widget          | Description                                   | Default                         |
|------------------------|-----------------|-----------------------------------------------|---------------------------------|
| `version`              | select          | CloudBeaver module to load                    | `"apps/cloudbeaver/25.0.4"`    |
| `enable_extra_modules` | check_box       | Toggle extra module loading                   | unchecked                       |
| `extra_modules`        | text_field      | Additional environment modules to load        | `""`                            |
| `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                           | `2`                             |
| `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.server.cloudbeaver/issues).

## References

- [CloudBeaver](https://cloudbeaver.io/) -- the database management tool
  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 CloudBeaver 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!

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions