Skip to content

docs: lead installation guide with Docker/Apptainer over from-source #889

Description

@sevmag

Suggestion

The current installation page leads with the from-source / CVMFS instructions and only mentions the Docker & Apptainer images further down. For most users — and especially on HPC clusters where Apptainer is already available — pulling the pre-built image is the fastest, most reliable way to get started.

I'd propose reorganising docs/source/installation/install.rst so that:

  1. The page opens with a short pointer to the Docker/Apptainer section as the recommended path.
  2. Docker & Apptainer Images comes first, framed as the default.
  3. Installing From Source follows, framed as the option for writable/editable installs or systems without a container runtime.
  4. The IceTray subsection under "From Source" is rewritten to point back up to the IceTray+GraphNeT image as the preferred route, with the CVMFS instructions retained as a fully-supported alternative for users who prefer working directly inside a CVMFS environment.

No technical content changes — just ordering and framing.

Motivation

  • I actually didn't know about the dockers really untill this week
  • I meet some people who had issues getting GraphNeT to work on their HPC clusters were using the Docker just to run stuff is probably easier
  • The IceTray subsection already says "we highly recommend to instead use our existing Docker images", but a new user has to scroll past a full CVMFS recipe to find that out.
  • HPC users often can't install from source on the bare cluster — for example RHEL/Rocky 8 nodes ship glibc 2.28, while pyg_lib's libpyg.so in the PyPI wheels at data.pyg.org requires GLIBC_2.29, so an pip install -e .[torch-XX] outside of CVMFS/conda-forge tends to fail at import time. The pre-built images sidestep this entirely.
  • CVMFS-based IceTray + GraphNeT setups are still fully supported and remain documented under "From Source"; this is purely a reordering/framing change.
  • The pre-built images already cover both CPU and GPU and are autobuilt per release, so leading with them better matches what's actively maintained.

I have a local rewrite ready and am happy to open a PR if there's interest.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions