Developer documentation

This is the developer documentation for this repository. See this primer SURF ResearchCloud for end-user documentation.

Below is a section for playbooks and a section for roles (reusable items that can be included in a playbook). The playbook and roles can be used stand-alone (run them locally on the target host), but are designed with the goal of deploying them in the deployment of a ResearchCloud workspace.

Contributed playbooks and roles should meet criteria specified in our item quality checklist.

External component repositories

This repository contains the bulk of UU’s ResearchCloud components for Unix/Linux workspaces, which are based on Ansible playbooks, and it also provides reusable roles as a collection. This documentation is exclusively for the playbooks and roles contained in this repo.

However, some components are not part of this repository and can be found elsewhere. This can be for several reasons (see below). Below is a list of important UU-maintained ResearchCloud components outside of this repository. Documentation should be contained in these external repositories.

Name	Description	Component type	Why not in this repo?
Grobid	Grobid can help you perform bibliographic analyses on scientific papers.	Docker Compose	Non-Ansible
Galaxy	Galaxy is a workflow engine for bioinformatics.	Ansible	Non-standard access rights
ibridges-ansible	A component to easily download iRODS collections to a workspace.	Ansible	Available as a separate collection
researchcloud-items-win	Various components targeting Windows workspaces	PowerShell	Non-Ansible

Components for specific research projects (not intended for general use) should preferably also be stored in a separate repository. They can use the roles in this repo by installing it as a collection.

Installing as a collection

The roles and playbooks in this repository can also be installed as an Ansible collection. The collection is named uusrc.general. After installation, this means you can use the roles from this repository, for example as follows:

roles:
    - role: uusrc.general.fact_regular_users

To install the collection you have two options:

install manually with ansible-galaxy collection install git+https://github.com/utrechtuniversity/researchcloud-items.git
add this repository to your requirements.yml:

---
collections:
  - name: https://github.com/UtrechtUniversity/researchcloud-items.git
    type: git

Playbooks

The status of a playbook is either Experimental or Supported. Supported playbooks are subjected to automated testing and must be fully documented.

For public items in the SURF Research Cloud catalog, this status should be indicated in the description field of the catalog plugin item.

Supported

agisoft install Agisoft Metashape
aptly serve apt repositories on the workspace
ibridges userfriendly commandline client for iRODS
icommands commandline tools for iRODS data grid
irods_tools install both iBridges and icommands command line tools
irods_sync sync folders from iRODS or Yoda to the workspace at creation time
flask_app serve a Flask app with Nginx, optionally with SRAM authorization.
matlab Data analysis and simulation suite
miniconda Python development
python-workbench Python development
reverse_proxy add reverse proxies to the SRC-Nginx environment
robotuser agent used for remote filesystem mounts
r-workbench R development
stata Stata18 statistical analysis suite
security_updates automatic updates for Ubuntu
shared_directories create shared data directories for regular users
transferuser dedicated user for file exchange with remote host

Experimental

anaconda python data science development
asreview machine-learning powered application for systematic reviews
camunda a business process workflow suite
camunda-modeler part of the camunda suite
ephor selected roles for ephor use-case
irods-desktop desktop application tools for iRODS data grid
keycloak OpenIDConnect/SAML Server

Roles

The status of a role is either Experimental or Supported. Supported roles are subjected to automated testing and must be fully documented.

Supported

agisoft install Agisoft Metashape
aptly_add add packages to Aptly repositories on the workspace
default_group set desired groups as default for regular users
desktop-file add desktop icons and login items for custom apps
fact_regular_users facts about users on the system
fact_workspace_info facts about the workspace, and groups and users from the CO (SRAM)
ibridges installs iBridges, a userfriendly commandline client for iRODS (GUI and/or CLI)
install_role
keycloak
matlab
miniconda
nginx_reverse_proxy
nginx_uwsgi
poetry
pip install pip
pipx_install_systemwide install pip packages in a shared directory for all users
pyenv install pyenv and use it to install custom python version
robotuser
rstudio
runonce
security_updates
sshfs_configrobot
sshfs_mount
sshfs_cleanup
system_python install latests version of python available through the system package manager
tidyverse_dependencies
transferuser
uu_generic generic uu flavouring for workspaces
uv lightning fast python version and dependency manager