This repository contains the materials for the iBridges training. It
- introduces RDM concepts and how they are implemented in iRODS
- takes beginners and non-technical researchers through the GUI and CLI
- introduces the basics of the iBridges Python API to scientific programmers
The repository also contains ansible scripts to build a training instance which deploys the policies discussed in the training, it sets up the users and the training data.
If you are new to Ansible, start with USAGE.md. This file describes what the package contains and how it is put together.
Plain server (install_irods.yml)
- PostgreSQL with the
ICATcatalog database - iRODS server (default version 4.3.5), iCommands and the PostgreSQL plugin from the official RENCI apt repository
- A systemd service (
irods) that starts the server at boot - Zone
tempZone, administratorrods, default resourcedemoResc
Training server (setup_training.yml): the plain server plus
- An extra resource
TrainingRescon a separate path (default/data/10gb); the path is made writable for theirodsservice account - 30 users
irods1...irods30(typerodsuser, no password, set by hand later) - An administrator
training_admin(typerodsadmin, no password) - Group
trainingwith all 30 users andtraining_admin - Group
datastewardswithtraining_admin - Event rules in
/etc/irods/hooks.re, registered inserver_config.json - Training data uploaded to iRODS with its metadata, owned by
training_admin
Maintenance playbooks
reset_users.yml: empties the home collections of the training users and invalidates their passwords (between two courses)cleanup.yml: removes iRODS from the machine again
| Where | What |
|---|---|
| Your computer ("control node") | Linux or macOS, Python 3, Ansible (recent ansible-core), the community.postgresql collection |
| The VM ("target") | Ubuntu 24.04 (or 22.04), amd64, SSH access, a user with sudo, Python 3 |
| Network | SSH (22) from you to the VM; iRODS ports 1247 and 20000-20199 for clients |
python3 -m venv .venv && source .venv/bin/activate
pip install ansible
ansible-galaxy collection install community.postgresql
# put the VM address in inventory.ini, then:
ansible -i inventory.ini irods -m ping
ansible-playbook -i inventory.ini setup_training.ymlThen set the user passwords by hand (see USAGE.md).
| Playbook | Purpose | Safety switch |
|---|---|---|
install_irods.yml |
Plain iRODS server only | none |
setup_training.yml |
Plain server + everything for the training | none |
reset_users.yml |
Delete the data of the training users, invalidate passwords | -e reset_users_confirm=true |
cleanup.yml |
Remove iRODS, its database, users and data from the machine | -e irods_cleanup_confirm=true |
setup_training.yml does not need install_irods.yml to be run first: the training
role depends on the plain role and pulls it in.
All playbooks are safe to run again. Existing users, groups, resources and data are
detected and left alone, so a second run should report changed=0.
Installs PostgreSQL and iRODS and runs the one-time setup. Main steps, in order:
- Install
acl(needed by Ansible to run tasks as thepostgresuser) - Install PostgreSQL, create the
irodsdatabase user and theICATdatabase - Add the RENCI apt repository for the release of the VM (
nobleorjammy) - Install
irods-server,irods-runtime,irods-icommandsandirods-database-plugin-postgres, all pinned to the same version - Make the VM's own hostname resolve to a local address in
/etc/hosts(iRODS setup refuses to run otherwise) - Run
setup_irods.py, answers come fromtemplates/setup.input.j2 - Install and start the
irodssystemd service
Depends on irods. Creates the resources, users, groups, installs the rules and uploads
the datasets. Uploads run as the iRODS service account, so the users need no password
for the setup to work.
For each training user: takes ownership of the home collection with ichmod -M
(an iRODS administrator has no automatic access to user homes), removes everything in
it with irm -rf, empties the trash, and sets a random password nobody knows.
Stops the service, drops the ICAT database and the irods database user, purges all
irods-* packages, deletes /etc/irods, /var/lib/irods and the irods user, removes
the apt repository, and removes the home and trash folders from the extra resource
vaults. PostgreSQL itself is kept unless you ask for it to be removed.
Settings live in the defaults/main.yml of each role. Do not edit them for secrets: use
an Ansible vault (see USAGE.md).
- Changing
irods_versionre-installs packages, but the one-time setup only runs once (it is skipped when/etc/irods/server_config.jsonexists). A major upgrade such as 5.x needs its own procedure and has not been tested; iRODS 5 setup prompts may differ from the answer file intemplates/setup.input.j2. - Database passwords and keys are read once, at setup time. Changing them in the variables later does not change an existing installation.
- cloud-init may rewrite
/etc/hostsafter a reboot. A running iRODS is not affected; re-run the playbook before running a new setup. - Tested on Ubuntu 24.04 with iRODS 4.3.x.
