Skip to content

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

@sevmag

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

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions