Appverse Contributor Documentation

1. What Is the Appverse?

The Appverse is a shared catalog of Open OnDemand app configurations for HPC environments. The goal is to improve reuse and share deployment patterns instead of rebuilding them from scratch.

In simple terms:

• Software = the tool (e.g., Jupyter, RStudio, a visualization app)
• App = the Open OnDemand configuration that launches that software on an HPC system

This guide is for developers, HPC admins, and anyone who wants to contribute or improve apps in the catalog.

2. App Types

3. Tags & Discoverability

Good tagging makes your app easier to discover in the catalog.

Implementation Tags (for Apps)

Implementation tags describe how an app runs:

• Containerized (Docker, Singularity/Apptainer)
• GPU-enabled
• Classroom-ready

Topics (for Software)

Research area(s) of the associated software (e.g., AI/ML, genomics, chemistry, materials science).

Tags (for Software)

Tags from the Connect.CI tag taxonomy of the associated software.

Tip: Apps with good tagging are significantly easier to find. Aim for at least 3-5 relevant tags.

4. Contributing an App

When to Contribute

Apps for software are always encouraged.

If the software already has app implementations, consider:

1. Modified an existing app? Contribute changes back to the original repository rather than publishing a new version. Forks that diverge silently create maintenance burden for everyone (see Best Practices: Avoid Fork Rot).
2. Only changed site-specific configuration? That likely doesn't warrant a new app — it's working as intended. Document your configuration instead.
3. Added significant new functionality? (e.g., GPU support, containerization, a different execution model) That's a good candidate for a new app.

High-Level Workflow

1. Prepare your repository with required files and metadata
2. Create a new App entry linked to the repository in the Appverse
3. Review and validation (see Reviewer Checklist)
4. Ongoing maintenance

Currently we support repositories containing single apps. In the future we are considering adding packages of apps that work together; these could be distributed via repositories containing multiple apps.

5. Repository Essentials

Each app must live in a public repository (GitHub; GitLab support may be added in the future).

Required Files

Recommended Files for Batch Connect Apps

The manifest.yml

This file defines how your app appears in the catalog. It must include:

name: My App Name
category: Interactive Apps        # Groups in navigation menus
subcategory: Servers              # Secondary grouping
role: batch_connect               # For interactive batch apps
description: |
  A brief description of what this app does
  and what it launches.

Optional but helpful fields:

icon: icon.png                    # Custom icon path
url: ''                           # URL override (usually auto-generated)
new_window: false                 # Open in new browser window
caption: Launch My App            # Custom button text
metadata:
  field_of_science: Chemistry     # Additional categorization of research domain

See the OOD manifest.yml reference for full details.

The README

Write for HPC administrators who need to deploy your app on their system.

Use the Appverse README Template as your starting point. It provides the standard section structure. A good README should cover:

1. Overview — what the app launches and who it's for
2. Features — key capabilities of this OOD app (not just the upstream software)
3. Requirements — compute node software, OOD version, scheduler
4. Installation — step-by-step deployment instructions
5. Configuration — what to customize and where (cluster names, paths, module names)
6. Troubleshooting — common issues and solutions
7. Testing — where it's been deployed and how to verify installation
8. Known limitations — what doesn't work, what's untested

See the README template with examples for a filled-in version showing what good content looks like in each section.

Example of a strong README in the wild: EpiGenomicsCode/ProteinStructure-OOD — includes features, prerequisites, installation, usage for multiple engines, monitoring, and troubleshooting.

Example of a weak README: A README that only contains the project name and a contact email. This tells deployers nothing about what they need to install or configure.

Best Practices for Repository Setup

• Avoid hardcoded cluster paths — use variables or configuration files so others can adapt your app without editing core scripts.
• Centralize configuration — there should be one clear place for site-specific settings. Don't scatter paths and module names across multiple files.
• Use release versions — tag releases with semantic versioning (e.g., v1.2.0) so others can pin to stable versions.
• Include a CHANGELOG — helps deployers understand what changed between versions and whether they need to update.

6. How Apps Get Synced

The catalog pulls information from your repository daily. The sync can also be triggered manually if needed.

Currently only GitHub repositories are supported, but GitLab support may be added in the future.

What Gets Synced

• Repository metadata (name, description, topics)
• manifest.yml contents
• README for display in the catalog
• Release/tag information

Keeping Things Current

After making changes to your app:

1. Update the README if behavior changed
2. Update the CHANGELOG
3. Create a new release tag if it's a significant update
4. The catalog will pick up changes on the next sync cycle

7. Review, Maintenance & Community

Review Process

New apps are evaluated against the Reviewer Checklist and the Best Practices Guide. Reviewers look for:

• Complete metadata and documentation
• Clear, portable configuration
• Adherence to Open OnDemand conventions
• An open source license

Maintenance

App maintainers are responsible for:

• Keeping metadata current
• Updating documentation when things change
• Responding to breaking changes in Open OnDemand or upstream software
• Addressing issues and pull requests from the community

Inactive apps may be archived, but we prefer revitalizing them with community help.

Community & Governance

• Join the Appverse Affinity Group to connect with other contributors and stay informed
• Follow contribution guidelines and code of conduct
• Propose new tags or app types through discussion
• Major policy decisions are community-driven
• Join the OOD Discourse for community support and monthly Tips & Tricks calls

Appendix

Open OnDemand References

Standard Batch Connect App Structure

my-app/
├── manifest.yml          # App metadata (required)
├── form.yml              # User form (or form.yml.erb for dynamic forms)
├── submit.yml.erb        # Job submission config
├── icon.png              # App icon
├── README.md             # Documentation (required)
├── LICENSE               # Open source license (required)
├── CHANGELOG.md          # Version history (recommended)
├── view.html.erb         # Connection view template
├── info.md.erb           # Pre-launch info panel
├── completed.md.erb      # Post-completion message
├── form.js               # Client-side form logic (optional)
├── template/
│   ├── before.sh.erb     # Pre-launch setup
│   ├── script.sh.erb     # Main launch script
│   └── after.sh.erb      # Cleanup script
└── docs/                 # Additional documentation

Glossary