Using openVRE - inab/openVRE GitHub Wiki
This section guides you through installing, configuring, and running dockerized openVRE for the first time.
You can deploy openVRE via the Production Tutorial or for quick local testing via the Development Tutorial.
2.1 Installation & Access
openVRE provides a central manager and user interface for your local compute infrastructure.
Several additional components (see the Core Components) are required to build a fully operational VRE deployment.
🐋 Docker-Based Architecture
The openVRE main branch provides the standard, containerized version of openVRE, including all essential services required to deploy a fully functional computational infrastructure.
While the underlying architecture remains identical to a manual installation (legacy branch), this version packages all components into Docker containers for ease of deployment, portability, and scalability.
2.1.1 Installation Guide
The installation process involves setting up all required services, including the core web application, authentication, and resource management layers.
Production Tutorial
For a full-scale production deployment of openVRE, follow these steps:
- Deploy to on-premises or cloud-based infrastructure with the necessary security certifications
- Configure Authentication, HashiCorp Vault, and MongoDB for the production environment
- Use manual installation if extensive customization of components or domains is required
| Deployment Method | Documentation |
|---|---|
| Containerized (Production) | Install.md |
Development Tutorial
For quick local setup and testing, you can deploy an out-of-the-box containerized openVRE instance.
This setup includes the openVRE core service and all minimal dependencies — authentication, local SGE queue, MongoDB, and other components needed for a self-contained test environment.
| Deployment Method | Documentation |
|---|---|
| Containerized (Recommended) | Install.md – Dev Branch |
Example Quick Start:
# Clone the Dockerized development branch
git clone https://github.com/inab/openVRE-core-dev.git
cd openVRE-core-dev
# Build and start containers
docker compose up -d
# Access the interface
open http://localhost:8088
Manual Installation - (Deprecated)
For environments where containerization is not possible, you can follow the manual installation guide provided in the main repository:
📄 Step-by-step installation instructions
📦 openVRE source code repository
This guide details how to:
- Build the PHP-based web service
- Configure backend connections (databases, queues, authentication services)
- Start and verify the platform components manually.
2.2 User Interface Overview
The main landing page presents a clean, intuitive user interface that foregrounds the core tools available within the platform.
An organized navigation menu on the left guides users through different sections that correspond to key phases of the research lifecycle, promoting a logical and streamlined workflow.
Users begin by authenticating through the “Log In” option located in the upper-right corner.
After successful authentication, they access their personal workspace and profile session, which includes unique tokens for both identity and Vault-based secure access.
Within the profile, the “Linked Accounts” tab allows users to securely store credentials required for connecting to external computing resources or data repositories integrated within the platform.
Once logged in, users are redirected to their personalized dashboard, which displays project-specific data, available tools, and workflows.
Navigation menus provide easy access to key sections such as Data Management and Tool Execution, either from workspace boxes or directly through the sidebar.
2.3 Data and Repository Management
The “Get Data” section enables users to browse datasets, validate metadata, and upload or download files.
Ensuring metadata compatibility is essential—data must be available and correctly formatted before job submission, as tools only process inputs matching their expected metadata and formats.
2.3.1 Working with External Data Repositories
Users can connect to and import data from external sources and repositories such as EGA, euroBioImaging, or Molgenis.
Integration with OpenStack Object Storage (Swift) provides:
- Anonymous read-only, ACL-defined, or temporary access
- Storage hierarchy mirroring the container structure of the object storage
- Secure token management through Vault-based secrets and application credentials
Data transfers are performed programmatically using cURL commands or the OpenStack client interface.
2.3.2 Uploading and Organizing Data
Users can import or upload data through multiple options:
- Drag and drop multiple files or create new text files within the workspace
- Import from URLs or external repositories
- Maximum upload size per file: 4 GB (configurable)
- Metadata is required to ensure data traceability and compatibility
Example datasets are also available for training and demonstration purposes, allowing users to test workflows without uploading personal data.
For developers: See Implement a New Data Interface, Register a New Linked Site, and Set a New Linked Account for extending data integration capabilities.
2.4 Running Tools and Workflows
In the “Run Tool” section, users can select analysis tools or workflows, view descriptions, and configure execution parameters.
Available tools can run across different execution environments, including local servers, HPC clusters, or cloud platforms, based on resource availability and user authorization.
2.4.1 Monitoring Executions
After job submission, openVRE provides real-time monitoring of the analysis.
Users can view status updates, queue information, and resource usage directly from the workspace dashboard.
2.4.2 Viewing Results and Outputs
Upon completion, results are stored in the user’s workspace for persistent access.
If the job was run in anonymous mode, results are not persistent and should be downloaded during the active session.
For developers: To integrate new tools, refer to Bring Your Own Tool, Register a New Tool, and Register an Interactive Tool.
2.5 Visualization and Results
openVRE supports built-in visualizers to explore and interpret analysis outputs directly within the interface.
2.5.1 Visualizers
Visualizers allow for interactive result exploration (e.g., genome browsers, 3D molecule viewers, or image analysis dashboards).
They are dynamically registered and can be extended by developers through the registration of an interactive tool module.
2.5.2 Common Visualizer Examples
- BioJS components for sequence and protein structure visualization
- Plotly.js dashboards for data analytics
- 3Dmol.js for molecular structure exploration