index.md

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

Experimental

• anaconda
• asreview
• camunda_modeler
• camunda_server
• irods_repo
• irods_icommands
• irods_iselect
• irods_skel
• rstudio