3. Developing and Administering OpenVRE

This section describes the core configuration, system setup, and administrative tasks needed to deploy, customize, and maintain openVRE in production or development environments.
It is primarily intended for developers, integrators, and system administrators.

3.1 Core Configuration and Setup

The following topics guide you through the initial configuration and administration of the VRE environment.
They include visual interface customization, manual SGE setup, Keycloak authentication, and HashiCorp Vault integration.

3.1.1 Apply Manual SGE Configuration

Manual configuration is required only for custom SGE cluster setups, where Docker-based automation is not used.

• sgecore username

Before initializing SGE to recognize jobs sent from the frontend, identify the Docker hostname:

docker exec -it sgecore /bin/bash
qconf -as ${FRONT_END_HOSTNAME}
qconf -mconf   # change UID from 1000 to 33

• sgecore usage permissions

Grant SGE proper permissions to use Docker:

groupmod -g 120 docker    # or adjust to your system's Docker group
usermod -aG docker application

chown root:docker /var/run/docker.sock
chmod 660 /var/run/docker.sock

3.1.2 Keycloak Configuration

Ensure the user and secret in Keycloak match your .env file configuration. Some systems may require allowing Keycloak access through iptables:

sudo iptables -I INPUT -s {keycloak internal IP} -p tcp --dport 8080 -j ACCEPT

Retrieve Client ID and Secret from the Keycloak admin console at:

http(s)://{$FQDN_HOST}/auth/admin

Update the .env with the credentials to enable VRE access.

3.1.3 HashiCorp Vault Configuration

• Keycloak Integration for Vault

1. Access the Keycloak admin console through http://localhost:9099/auth and navigate to your realm.

2. Locate your existing client, in this case is the open-vre one.

3. In the client settings, configure the following:

   • Root URL:

     https://$FQDN_HOST/
     

     Replace $FQDN_HOST with your fully qualified domain name (e.g., vre.disc4all.eu).

   • Valid Redirect URIs:

     https://$FQDN_HOST/*
     

     Additionally:

     http://$FQDN_HOST/ui/vault/auth/oidc/oidc/callback
     

     Ensure $FQDN_HOST is replaced with the correct host name for your deployment (e.g., vre.disc4all.eu).

4. Create a new client (on the right side of the clients table)_ open-vre-vault_ for Vault with the same URLs as above, with the same root Url as open-vre client.

5. Configure the following for the new client:

• Root URL:

  https://$FQDN_HOST/
  

• Valid Redirect URIs:

  https://$FQDN_HOST/*
  

  Additionally:

  http://$FQDN_HOST/ui/vault/auth/oidc/oidc/callback
  

Replace $FQDN_HOST with your domain (e.g., vre.domain.eu).

6. Save the changes to the client configuration to ensure the URIs are authorized by Keycloak.

With the above configuration, Vault will be able to interact with Keycloak for OpenID Connect (OIDC) authentication, once it is configured manually on the Vault. Before interacting with the Vault Server container, for the next configuration step, is necessary to retrieve the JWKS validating public key, directly from the Keycloak Realm. Accessing the Admin Keycloak Interface through these steps :

1. Access the Vault-Server info using this command:

curl http://$FDQN_HOST/auth/realms/open-vre/protocol/openid-connect/certs

2. Copy the results so to copy the n and the e values from the response array;

3. Redirect in the vault/ dir;

4. Substitute the vaules you had saved in the pem.py script;

5. Launch the pem.py script:

python3 pem.py >> public-key.pem
mv public-key.pem config/

6. Make sure that the key was saved in the vault/config/ dir.

• Vault GUI unseal

First time Vault is up, it is possible to access and explore the Vault via the UI.

You can connect to it via http://hostname:8200/ui/vault/. There you would be able to set the number of keys you want to produce and to use to unseal the Vault.

Save the keys!

Once you proceed on the unseal process, and the Status of the Vault turns to green, from the Admin page it would be possible to establish some configuration. For example, setting up some policies.

Click on the Policies section. Here with the button Create ACL Policy, we will add two policies: OIDC and JWT, for the Vault to communicate with the Keycloak local server.

The policies are gonna be named jwt-role-demo:

path "auth/jwt/role/demo" {
  capabilities = ["create", "read", "update", "delete"]
}

path "secret/*" {
  capabilities = ["create", "read", "update", "delete"]
}

path "auth/token/lookup-self" {
  capabilities = ["read"]
}
path "auth/token/renew-self" {
  capabilities = ["update"]
}
path "auth/token/revoke-self" {
  capabilities = ["update"]
}

and oidc-role-myrole:

path "auth/oidc/role/myrole" {
  capabilities = ["create", "read", "update", "delete"]
}

path "secret/mysecret" {
  capabilities = ["create", "read", "update", "delete"]
}

Rest of the configuration could be done manually.

• Vault manual unseal

First time Vault up, access the containers in interactive mode, to execute the init and save elsewhere the 'Unseal keys' just generated:

docker exec -ti vault-server vault operator init 

On every Vault restart, use the following command to unseal the vault using 3 out of the 5 Unseal Keys generated during the init.

docker exec -ti vault-server vault operator unseal SECRET_KEY1
docker exec -ti vault-server vault operator unseal SECRET_KEY2
docker exec -ti vault-server vault operator unseal SECRET_KEY3

• Vault manual setup

Considering an external JWT Authorization Token service as a middle identification layer to access the Vault and its secrets, it has to be properly registered. Here are the command to follow to instatiate a JWT Authorization service for Keycloak:

docker exec -ti vault-server /bin/sh
vault login # with ${Intial Root Token}

vault auth enable jwt
vault auth enable oidc

#Policy, if not done by UI
cd vault/config
vault policy write jwt-role-demo jwt-role-demo.hcl
vault policy write oidc-role-myrole oidc-role-myrole-policy.hcl

#Role
vault write auth/oidc/role/myrole allowed_redirect_uris="[http://$HOSTNAME/ui/vault/auth/oidc/oidc/callback, http://localhost:8250/oidc/callback]" user_claim="sub" #Hostname can coincide with $FQDN_HOST
vault write auth/jwt/role/demo bound_audiences="account" allowed_redirect_uris="http://localhost:8250/oidc/callback" user_claim="sub" policies=jwt-role-demo role_type=jwt ttl=1h
vault write auth/jwt/role/demo role_type="jwt"
#vault write auth/jwt/role/demo bound_audiences="account"

#Configuration
#The public key can be retrieved directly from the Keycloak Realm (from the JWKS endpoint)
vault write auth/jwt/config default_role=demo bound_issuer="https://$KEYCLOAK_REALM" [email protected] bound_audiences="account"

#Secrets
vault secrets enable -path=secret/mysecret kv-v2

---

3.2 Tools Integration

openVRE integrates modular computational components called Tools, enabling reproducible and extensible research workflows.
These tools can be brought, configured, and executed directly from the platform by researchers or administrators.

3.2.1 Tools Overview

openVRE Tools are modular computational units within the openVRE analysis platform that enable diverse research workflows.
Developed by third-party tool developers, these tools can be parameterized by researchers to suit specific project needs.
Once configured, they are executed by the platform’s compute back end.

Each tool runs within a software container (e.g., Docker, Singularity), ensuring compatibility, portability, and isolation — making integration seamless and reproducible.

3.2.2 Types of Tools

There are two main categories of tools in openVRE:

• Non-Interactive Tools — Operate in batch mode without user input. Ideal for large-scale or automated analyses.
• Interactive Tools — Provide a web-based interface for real-time interaction and visualization of results.

3.2.3 How to Bring Your Own Tool

openVRE supports multiple methods for integrating your own tools:

• Bring Your Own Tool — Manual integration of tools using the openVRE API and configuration templates.
• Bring Your Own Tool — Dockerized — Container-based approach for portable and reproducible tool deployment.
• Register a New Tool
• Register a New Interactive Tool

Each guide provides step-by-step instructions for registration, configuration, and validation within the platform.

3.3 Repository and Resources

openVRE supports modular integration of external repositories and resources, enabling smooth data exchange and access to computation or visualization back ends.

3.3.1 Repository Interfaces

openVRE provides pre-built repository interfaces that allow integration with popular research data storage and sharing services. These interfaces enable seamless transfer, management, and publication of data from within openVRE.

3.3.2 Supported Repository Interfaces

• OpenStack Swift Object Storage — Scalable, distributed storage service used for archiving large research datasets.
• WebDAV-based Integrations:
  • Nextcloud — Open-source file sharing and collaboration platform supporting WebDAV for secure access and synchronization.
• HTTP API-based Integrations:
  • XNAT (eXtensible Neuroimaging Archive Toolkit) — Biomedical and neuroimaging data management platform.
  • ArrayExpress — EMBL-EBI repository for gene expression and functional genomics datasets.
  • BigNASim — Repository for nucleic acid simulations and bioinformatics data involving DNA/RNA structures.
• European Genome-Phenome Archive (EGA) — Secure repository for sensitive genomic and phenotypic data, supporting controlled-access research.
• B2SHARE — EUDAT open data repository for storing, publishing, and sharing research data with metadata compliance.
• Rclone (in progress) — Command-line tool supporting 40+ cloud storage backends, ideal for syncing and secure data transfers.

3.3.3 Puggable Resources

openVRE supports puggable resources, which are modular connectors for extending access to external computational, data, or visualization services. Administrators can configure new back ends or link remote HPC/cloud systems, enabling hybrid or distributed computing environments.

3.4 Sites and Linked Accounts

In openVRE:

• Sites represent external infrastructures — such as HPC clusters, cloud services, or data repositories — that can be registered and managed by admins.
• Linked Accounts securely store user-specific credentials and authentication tokens, enabling access to those connected sites.
• These connections are handled securely through Vault-based secret management and Keycloak authentication integration.

For detailed instructions on extending openVRE with external infrastructures and user authentication, see the following dedicated guides:

3.4.1 Register a New Linked Site

Steps to define and register a new computational, storage, or data site in openVRE.
See: Add New Linked Site

3.4.2 Adding a New Data Repository

Instructions for integrating new data repositories or catalog interfaces into the platform.
See: Adding a New Data Repository

3.5 Graphic and UI Extensions

These extensions enable developers to enhance and customize the openVRE user interface and visual experience.

3.5.1 Graphic configuration

For a full extensive tutorial on the graphic modules of the VRE, refers to the graphic configuration page

3.5.2 Extending Frontend Components

Guidelines for extending or adapting frontend elements to integrate new components, menus, or UI modules.
Examples include adding menu tabs for external resources or customizing account settings views.
See also: Integrating Front-End References

---

3.6 Related Topics – Admin Configuration

For further extensions and configuration details on the administrative and development side, see:

• Register a New Tool
• Register a New Interactive Tool
• Implement a New Data Interface
• Register a New Linked Site