[m-reuter]

Follow-up to #948.

One command on every system

• The launcher is now tools/fastsurfer, without .py, so a downloaded copy cannot shadow the Python package fastsurfer. ruff includes it explicitly, as recon_surf/fs_time.
• On a Mac with Apple silicon it runs the installed macOS package (/Applications/FastSurfer<version>, set up by its macos_setup_fastsurfer.sh, as in the console), with the same flags and --exec as on Linux. It chooses among installed versions as among images: one runs, several stop with a list, --image 2.6.0 chooses. --update downloads the package of the newest release (or of --image <version>), found through GitHub's release API, and opens the macOS Installer. --runtime docker still runs an image under emulation.

Download and docs

• The docs build publishes the launcher next to the pages (html_extra_path), so it downloads from https://deep-mi.org/FastSurfer/stable/fastsurfer, a real file that works with curl; GitHub Pages cannot redirect. The link works from the next release on.
• The quick start uses the same commands on every system: only what to install differs (a container runtime, or the macOS package). The README and the Linux and macOS pages show the launcher.

Launcher

• --exec PROGRAM ARGS runs another program of the image. --exec brun_fastsurfer.sh and --exec long_fastsurfer.sh take FastSurfer's flags and are handled like run_fastsurfer.sh (path flags, several paths after --t1s/--t2s, the license), so no launcher option shares a name with the scripts' flags; run_fastsurfer.sh --long <template_id> passes through. Any other program, e.g. --exec nib-convert in.mgz out.nii.gz, runs in the current directory, shared with the container together with the directories of absolute paths in its arguments, with the newest installed image; with Docker it gets the input from a pipe or file (-i), and a terminal in one (-it). --exec=PROGRAM works too.
• AMD GPUs (experimental): without an NVIDIA GPU, or with --image rocm, the launcher runs the ROCm image on an AMD GPU found through the kernel driver (/dev/kfd), with --rocm (Apptainer) or the device, group and IPC flags (Docker). For a GPU whose family the image supports but whose exact architecture it lacks (e.g. gfx1032, the W6600), it sets HSA_OVERRIDE_GFX_VERSION. With both kinds of GPU, NVIDIA stays the default and a note names --image rocm.
• --runtime counts only the images of the runtime it names, while there is one.
• Python from python.org on macOS has no root certificates until its "Install Certificates" script runs; the launcher retries with the system's certificates instead of reporting Docker Hub as unreachable.

Tested on a Linux server (Turing GPU, Docker and Apptainer): --exec nib-convert and --exec bash, the image choice with several installed images, NVIDIA runs unchanged, --image rocm stopping without an AMD GPU. Tested on a Mac with Apple silicon with two package versions installed: runs through the package, the version choice, --update finding the package of an older release. The AMD path is not yet tested on AMD hardware, only with unit tests on a stand-in driver topology. Unit tests cover the paths for --exec and the scripts, the image and package choice, the argument split at --exec and the generated commands; lint tests keep the launcher's CUDA and ROCm versions in sync with gpu_support.py and pyproject.toml; the docs build passes with -W.

[Copilot]

🟡 Changes recommended

Unresolved argument-routing and stdin-forwarding bugs break supported launcher invocations.

4 open issues

• Preserve existing --long option semantics · New
• Support equals-form --exec arguments · New
• Pass brun flag to GPU request validation · New
• Keep stdin attached for non-terminal exec runs · New

What changed in this PR

This PR makes the container launcher the primary getting-started path and extends its execution and GPU support.

Changes:

• Publishes the launcher through the documentation site and updates installation examples.
• Adds longitudinal processing, arbitrary program execution, and experimental AMD GPU support.
• Improves runtime-specific image selection and HTTPS certificate handling, with expanded tests.

File	Description
tools/​fastsurfer_container.py	Extends execution modes, GPU support, and image handling.
test/​utils/​test_fastsurfer_container.py	Tests new launcher behavior and generated commands.
test/​lint/​test_launcher_builds.py	Checks ROCm build-version consistency.
README.md	Introduces launcher-first container usage.
doc/​overview/​QUICKSTART.md	Uses the launcher and synchronized platform tabs.
doc/​overview/​install/​LINUX.md	Documents launcher usage and AMD support.
doc/​overview/​CONTAINERS.md	Documents new modes and download location.
doc/​conf.py	Publishes the launcher alongside generated pages.

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Image reuse, custom-image AMD passthrough, and batch-script help forwarding have unresolved functional issues.

No open issues 🎉

4 resolved since last review

• Keep stdin attached for non-terminal exec runs
• Pass brun flag to GPU request validation
• Support equals-form --exec arguments
• Preserve existing --long option semantics

_{Review effort: Balanced}