shelley-bio build: executable file not found in $PATH

[fredjaya]

Expected behaviour

Building a module with shelley-bio build let's you run the software binary correctly. e.g.

shelley-bio build star
module load star
star

Steps to reproduce error

• Build STAR with shelley-bio works

shelley-bio build star

/usr/lib/python3.10/runpy.py:126: RuntimeWarning: 'shelley_bio.client.cli' found in sys.modules after import of package 'shelley_bio.client', but prior to execution of 'shelley_bio.client.cli'; this may result in unpredictable behaviour
  warn(RuntimeWarning(msg))
ℹ️  Running with elevated privileges: build star
╭──────────────────────────────────────────────── Version Information ─────────────────────────────────────────────────╮
│                                                                                                                      │
│  ℹ️  Version Selection                                                                                               │
│                                                                                                                      │
│  Available versions for star:                                                                                        │
│    • 2.7.11a--h0033a41_0                                                                                             │
│    • 2.7.11b--h43eeafb_0                                                                                             │
│    • 2.7.11b--h43eeafb_1                                                                                             │
│    • 2.7.11b--h43eeafb_2                                                                                             │
│    • 2.7.11b--h43eeafb_3                                                                                             │
│    • 2.7.11b--h5ca1c30_4                                                                                             │
│    • 2.7.11b--h5ca1c30_5                                                                                             │
│    • 2.7.11b--h5ca1c30_6                                                                                             │
│    • 2.7.11b--h5ca1c30_7                                                                                             │
│    • 2.7.11b--h5ca1c30_8                                                                                             │
│    ... and 38 more                                                                                                   │
│                                                                                                                      │
│  ⚠️  No version specified                                                                                            │
│  Building latest version: 2.7.11a--h0033a41_0                                                                        │
│                                                                                                                      │
│  To specify a version:                                                                                               │
│  shelley-bio build star/2.7.11a--h0033a41_0                                                                          │
│                                                                                                                      │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
╭─────────────────────────────────────────────────── Build Complete ───────────────────────────────────────────────────╮
│                                                                                                                      │
│  ✅ Module Built Successfully!                                                                                       │
│                                                                                                                      │
│  Tool: star                                                                                                          │
│  Version: 2.7.11a--h0033a41_0                                                                                        │
│  Module Path: /apps/Modules/modulefiles/star/2.7.11a--h0033a41_0.lua                                                 │
│                                                                                                                      │
│  To load this module:                                                                                                │
│  module load star/2.7.11a--h0033a41_0                                                                                │
│                                                                                                                      │
│  To list all modules:                                                                                                │
│  module avail                                                                                                        │
│                                                                                                                      │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

• Module shows correctly

module avail

------------------------------------------------------------------------------------------ /apps/Modules/modulefiles -------------------------------------------------------------------------------------------
   R/4.1.2    ansible/2.10.8    jupyter/2024.10    nextflow/24.10.2    nf-core/3.5.2    rstudio/2023.12.1    snakemake/6.15.1    star/2.7.11a--h0033a41_0

------------------------------------------------------------------------------------------- /opt/Modules/modulefiles -------------------------------------------------------------------------------------------
   shpc    singularity

Use "module spider" to find all possible modules.
Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".

• Module loads, but does not find the star binary

module load star
star

FATAL:   "star": executable file not found in $PATH

[Mitchob]

Summary

shelley-bio build successfully creates an Lmod module for tools found in CVMFS (e.g., STAR), and the module loads without error. However, the installed module does not expose the actual binaries on $PATH, so running the tool fails (e.g., star or STAR). The underlying cause is that Shelley’s generated modulefile assumes an executable name that doesn’t exist in the container and doesn’t provide real wrapper scripts on $PATH. The reliable fix is to use SHPC under the hood to install the container as a module (which generates working wrappers/entrypoints), while keeping Shelley’s UX and “look”.

Test Environment

Host image: Ubuntu 22.04 (Nectar)
CVMFS mounted at: /cvmfs/singularity.galaxyproject.org/all
Singularity present (warnings seen but functional)
Lmod modules working (can module use/module load)
SHPC available (shpc --version → 0.1.28)

Steps to Reproduce

Build STAR with Shelley:

shelley-bio build star:2.6.0b--0

Output:

ubuntu@shelley-test:~$ shelley-bio build star:2.6.0b--0
ℹ️  Running with elevated privileges: build star:2.6.0b--0
╭─────────────────────────────────────────────────── Build Complete ───────────────────────────────────────────────────╮
│                                                                                                                      │
│  ✅ Module Built Successfully!                                                                                       │
│                                                                                                                      │
│  Tool: star                                                                                                          │
│  Version: 2.6.0b--0                                                                                                  │
│  Module Path: /apps/Modules/modulefiles/star/2.6.0b--0.lua                                                           │
│                                                                                                                      │
│  To load this module:                                                                                                │
│  module load star/2.6.0b--0                                                                                          │
│                                                                                                                      │
│  To list all modules:                                                                                                │
│  module avail                                                                                                        │
│                                                                                                                      │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Load the module and run the tool:

module load star/2.6.0b--0
star

FATAL:   "star": executable file not found in $PATH

Expected behaviour is running the tool should succeed because the module exposes the container’s entrypoints on $PATH.

Why?

Shelley’s module file aliases the wrong command.
The generated Lua file contains set_alias("star", container_exec("star"))
But inside the STAR 2.6.0b–0 container the binaries are /usr/local/bin/STAR and /usr/local/bin/STARlong—there is no star binary. Evidence:

singularity exec /cvmfs/singularity.galaxyproject.org/all/star:2.6.0b--0 which STAR
# /usr/local/bin/STAR

singularity exec /cvmfs/singularity.galaxyproject.org/all/star:2.6.0b--0 ls -l /usr/local/bin | grep -i star
# -rwxrwxr-x ... STAR
# -rwxrwxr-x ... STARlong

No actual wrapper scripts are placed on $PATH.
The modulefile tries:

prepend_path("PATH", pathJoin(os.getenv("MODULEPATH") or "", "..", "wrappers", "star", "2.6.0b--0"))

but Shelley never creates the wrappers/.../bin tree with executable scripts. So, even if the alias were correct, nothing new lands on $PATH.

In Contrast with SHPC (works).
When we install via SHPC for a tag that exists in its registry, SHPC creates:
a modulefile that prepends the wrapper bin/ directory to $PATH, and
real wrapper scripts that call the right binary inside the container.

Example (success path we tested):

shpc install quay.io/biocontainers/star:2.7.10a--h9ee0642_0 \
  /cvmfs/singularity.galaxyproject.org/all/star:2.7.10a--h9ee0642_0 \
  --keep-path

module use ~/shpc/modules
module load quay.io/biocontainers/star/2.7.10a--h9ee0642_0. #This is ugly, I want to keep Shelleys file system
which STAR
# /home/ubuntu/shpc/wrappers/.../bin/STAR
STAR --version
# 2.7.10a

Inspecting SHPC’s module + wrappers shows the exact behaviour we want (PATH injection + wrapper calls to /usr/local/bin/STAR in the SIF). so any of the star commands will work...see wrappers:

ubuntu@shelley-test:~$ ls shpc/wrappers/quay.io/biocontainers/star/2.7.10a--h9ee0642_0/bin/
STAR  star-container  star-exec  star-inspect-deffile  star-inspect-runscript  star-run  star-shell

Additional Observations (Note: I demoed an older star version than in the shpc registry but then had to switch to a newer version to confirm shpc behaviour)

• Registry gap for old tags:
  SHPC’s remote registry does not have star:2.6.0b--0. shpc install therefore errors with “not a known identifier” and lists only the 2.7.x tags. That’s expected: SHPC installs known identifiers from its registry. General solution is to build you own local registry. This is a multistep process. Maybe too lengthy for our needs.
• Possible Lightweight solution for old tags (not tested):
  We don’t need to clone the whole SHPC registry. We can synthesise a tiny local filesystem registry entry for star:2.6.0b--0 that points to the CVMFS path and defines the correct aliases (e.g., STAR, STARlong), then shpc install will generate the proper module + wrappers.

Proposed Fix (I am not sure if this is viable, but is how I imagine making it work)

1. Use SHPC under the hood in shelley-bio build to perform the installation and generate wrapper scripts/aliases.
2. If the requested : isn’t in SHPC’s registry but exists in CVMFS, auto‑generate a single local filesystem registry entry:

• ~/.shelley/shpc-registry/quay.io/biocontainers//container.yaml
• Add a tags: stanza that points to the CVMFS image.
• Provide the correct aliases (e.g., STAR, STARlong). <--- I am not sure how to automate this part if it isnt self resolving. (Use an available version as a template??)
• Then call shpc install against that local registry.

3. Keep the “Shelley look”: preserve Shelley’s panels/output; optionally generate a thin “Shelley‑style” module that simply loads the SHPC module or prepends the SHPC wrapper bin/ dir to $PATH.

This approach would fix the PATH/entrypoint problem for all tools, handle older tags without cloning the entire registry, and keeps the user‑facing experience consistent.