Developer documentation

This is the developer documentation for this repository. See 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.

A note on Windows

This documentation concern ResearchCloud components for Unix/Linux workspaces, which are based on Ansible. There is a separate repository for Windows components (using PowerShell).

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

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
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
docker application container management
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

aptly_add add packages to Aptly repositories on the workspace
default_group set desired groups as default for regular users
desktop-file
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
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
transferuser
uu_generic generic uu flavouring for workspaces