Developer documentation

This is the developer documentation for UU’s primary repository containing components for SURF ResearchCloud. See this primer SURF ResearchCloud for end-user documentation. See here for an overview of secondary component repos.

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.

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
alphafold install DeepMind AlphaFold
aptly serve apt repositories on the workspace
asreview machine-learning powered webapplication for systematic reviews
custom packages download projects, install their dependencies into separate environments, and create Jupyter kernels for them
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
jupyterhub install JupyterHub
jupyter_rtc add Real-time Collaboration functionality to an existing JupyterHub.
flask_app serve a Flask app with Nginx, optionally with SRAM authorization.
matlab Data analysis and simulation suite
miniconda Python development
nextflow Nextflow workflow engine
openvscodeserver installs the OpenVSCode web IDE and serves it for all users
openrefine installs the OpenRefine data cleaning and manipulation webapp
python-workbench Python development
reverse_proxy add reverse proxies to the SRC-Nginx environment
robot-server agent used for remote filesystem mounts
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
uu_provisioning common tasks for UU workspaces

Experimental

anaconda python data science development
camunda a business process workflow suite
camunda-modeler part of the camunda suite
ephor selected roles for ephor use-case
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
alphafold install DeepMind AlphaFold
aptly_add add packages to Aptly repositories on the workspace
asreview_server
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
irods_repo
irods_icommands
irods_iselect
irods_skel
julia install the Julia language
jupyterhub install JupyterHub on the workspace, with SRAM auth.
jupyterhub_app install arbitrary applications as an extension for JupyterLab, or as a standalone app served with JupyterHub.
jupyterhub_rtc add real-time collaboration functionality to an existing JupyterHub.
jupyterhub_standalone_proxy use Jupyter Standalone Proxy to spawn an arbritary web application running as a logged in user.
keycloak
matlab
miniconda
nextflow Nextflow workflow engine
nginx_reverse_proxy
nginx_uwsgi serve uWSGI applications with the SRC-Nginx installation
openvscode install OpenVSCode server
openrefine installs the OpenRefine data cleaning and manipulation webapp
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
rust install the Rust language
require_src_docker
require_src_nginx
security_updates
sshfs_configrobot
sshfs_mount
sshfs_cleanup
system_python install latests version of python available through the system package manager
tidyverse_dependencies
tigervnc installs TigerVNC server
transferuser
uu_generic generic uu flavouring for workspaces
uv lightning fast python version and dependency manager