Update shelley installation & README

CHANGELOG.md

@@ -11,3 +11,10 @@ See [docs/MAINTENANCE.md](docs/MAINTENANCE.md) for the versioning policy and rel
 
 ### Added
 - GitHub Action (`update-tool-versions`) that checks pinned tool versions against upstream on a schedule (1 January and 1 July) and opens a pull request with any updates. See [docs/MAINTENANCE.md](docs/MAINTENANCE.md#5-github-actions-automation).
+
+### Fixed
+- Update tools to the latest version [PR #13](https://github.com/AustralianBioCommons/BioShell/pull/13).
+- Update README based on feedback [Issue #14](https://github.com/AustralianBioCommons/BioShell/issues/14).
+
+### Changed
+- Rename Shelley and update installation to use `uv`.

README.md

@@ -13,6 +13,9 @@ BioShell is built using Packer and Ansible, and is designed to run on OpenStack
 
 This repository contains configuration and automation for building a custom Ubuntu‑based BioShell and provisioning instances on OpenStack‑compatible cloud environments.
 
+### Documentation
+For usage instructions, see the [Bioshell Guide](https://sih.tools/bioshell-guide).
+
 ----------------------------
 ## Table of Contents
 ----------------------------
@@ -79,7 +82,7 @@ NOTE: Do not select an external/public network here
 
 In the Security Groups tab, ensure the following are listed under Allocated by clicking the up arrow in the Avialable groups:
 - **default** that allows outbound traffic and internal communication
-- **SSH-access security group** that allows inbound TCP port 22 from your IP or network
+- **SSH-access security group** that allows inbound TCP port 22 from your IP or network. Follow the [guide](https://tutorials.rc.nectar.org.au/sec-groups-101/03-create) to create one if you don't already have one.
 
 SSH access is required to log in to the instance.
 
@@ -204,7 +207,7 @@ packer init .
 
 ### Step 2: Prepare Packer build configuration
 
-Before running the build, review and update `[platform_name].pkrvars.hcl` to ensure the values match your OpenStack environment. If using a prepared config skip to step 3.
+Before running the build, review and update `[platform_name].pkrvars.hcl` in [`packer vars`](build/packer-vars) to ensure the values match your OpenStack environment. If using a prepared config skip to step 3.
 
 **Note: Example working configurations for [Nectar](build/packer-vars/nectar.pkrvars.hcl) and [Nirin](build/packer-vars/nirin.pkrvars.hcl) are included and were last successfully tested on 2 February 2026. The Nirin configuration requires you to add your project [network](#network-cloud-dependant).**
 
@@ -446,4 +449,4 @@ shelley-bio versions STAR
 
 # Launch interactive mode for guided help
 shelley-bio interactive
-```
+```

build/ansible/build-bioshell.yml

@@ -13,4 +13,4 @@
     - nextflow
     - rstudio
     - cvmfs
-    - shelley-bio
+    - shelley

build/ansible/roles/common/tasks/main.yml

@@ -158,11 +158,11 @@
 
 - name: Create ansible modulefile
   copy:
-    dest: "/apps/Modules/modulefiles/ansible/{{ ansible_version.string }}"
+    dest: "/apps/Modules/modulefiles/ansible/{{ ansible_target_version }}"
     content: |
       #%Module1.0
 
-      prepend-path PATH "/apps/ansible/{{ ansible_version.string }}/bin"
+      prepend-path PATH "/apps/ansible/{{ ansible_target_version }}/bin"
 
 - name: Ensure motd.d directory exists
   file:
@@ -181,21 +181,27 @@
       #                                                                #
       # Welcome to BioShell!                                           #
       #                                                                #
+      # To learn how BioShell is built, visit:                         #
+      #  https://github.com/AustralianBioCommons/BioShell              #
+      #                                                                #
+      # Documentation is also available at:                            #
+      #  https://sih.tools/bioshell-guide                              #
+      #                                                                #
       # A range of commonly used bioinformatics software is available  #
       # via CVMFS.                                                     #
       #                                                                #
       # To make the software folders visible, run:                     #
       #   cvmfs_config probe                                           #
       #                                                                #
       # If you need help finding and installing software,              #
-      # ask Shelley-Bio                                                #
+      # ask Shelley.                                                   #
       #                      _   .----.                                #
       #                     (_ \/      \_,                             #
       #                        `uu----uu'                              #
       # Basic commands:                                                #
-      # shelley-bio find <tool>                                        #
-      # shelley-bio search "<function>"                                #
-      # shelley-bio versions <tool>                                    #
-      # shelley-bio build <tool>                                       #
-      # shelley-bio interactive                                        #
+      # shelley find <tool>                                            #
+      # shelley search "<function>"                                    #
+      # shelley versions <tool>                                        #
+      # shelley build <tool>                                           #
+      # shelley interactive                                            #
       ##################################################################

build/ansible/roles/nextflow/tasks/main.yml

@@ -5,10 +5,20 @@
     state: present
   when: ansible_os_family == "Debian"
 
-- name: Set Java {{ java_version }} as default
-  alternatives:
-    name: java
-    path: /usr/lib/jvm/java-{{ java_version }}-openjdk-amd64/bin/java
+- name: Register Java {{ java_version }} as an alternative
+  command: >
+    update-alternatives --install /usr/bin/java java
+    /usr/lib/jvm/java-{{ java_version }}-openjdk-amd64/bin/java 1
+  args:
+    creates: /etc/alternatives/java
+  when: ansible_os_family == "Debian"
+
+- name: Set Java {{ java_version }} as the active alternative
+  command: >
+    update-alternatives --set java
+    /usr/lib/jvm/java-{{ java_version }}-openjdk-amd64/bin/java
+  register: java_alt_set
+  changed_when: "'link currently' not in java_alt_set.stdout"
   when: ansible_os_family == "Debian"
 
 - name: Create Nextflow directories

build/ansible/roles/shelley/tasks/main.yml

@@ -0,0 +1,49 @@
+---
+- name: Ensure prerequisites are installed (python3, curl, git)
+  apt:
+    name:
+      - python3
+      - curl
+      - git
+    state: present
+    update_cache: yes
+
+- name: Create /opt/uv directory
+  file:
+    path: /opt/uv
+    state: directory
+    owner: root
+    group: root
+    mode: '0755'
+
+- name: Check if uv is already installed
+  stat:
+    path: /opt/uv/uv
+  register: uv_binary
+
+- name: Install uv system-wide into /opt/uv
+  shell: curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR=/opt/uv sh
+  args:
+    executable: /bin/bash
+  when: not uv_binary.stat.exists
+
+- name: Verify uv installation
+  command: /opt/uv/uv --version
+  register: uv_version
+  changed_when: false
+
+- name: Symlink uv onto PATH
+  file:
+    src: /opt/uv/uv
+    dest: /usr/local/bin/uv
+    state: link
+    force: yes
+
+- name: Install shelley into system tool location, linked onto PATH
+  command: >
+    /opt/uv/uv tool install git+https://github.com/Sydney-Informatics-Hub/shelley
+  environment:
+    UV_TOOL_DIR: /opt/uv/tools
+    UV_TOOL_BIN_DIR: /usr/local/bin
+  args:
+    creates: /usr/local/bin/shelley

build/ansible/roles/singularity/tasks/main.yml

@@ -93,6 +93,13 @@
       module-whatis   "Sets up the Singularity system in your environment"
       prepend-path PATH "{{ singularity_prefix }}/{{ singularity_version }}/bin"
 
+- name: Auto-load the singularity module for every login shell
+  lineinfile:
+    path: /etc/environment
+    regexp: '^LMOD_SYSTEM_DEFAULT_MODULES='
+    line: 'LMOD_SYSTEM_DEFAULT_MODULES="singularity"'
+    state: present
+
 - name: Install shpc
   shell: |
     mkdir -p /opt/shpc/bin