Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sevmag wants to merge 1 commit into
base: main
Choose a base branch
from
Open

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 42 additions & 39 deletions docs/source/installation/install.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,48 @@ Quick Start
===========
Here we provide a quick start guide for getting you started with |graphnet|\ GraphNeT.

The easiest way to get started is with our pre-built Docker images — see `Docker & Apptainer Images`_ below. They ship GraphNeT, PyTorch and (optionally) IceTray ready to use, with both CPU and GPU variants, and can be run without sudo via Apptainer. If you instead need a writable install or an environment without a container runtime, see `Installing From Source`_.

@christianlocatelli christianlocatelli Jul 10, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would adapt this section a bit. Instead of "easiest way to get started", I would suggest to instead use something like: "The most reliable way for GraphNeT Users to get a working environment...".

I would also already mention in that section, that the Docker option is not available for KM3NeT so far. Otherwise KM3NeT Users reading it from top to bottom could be a bit mislead. Could we add a one-line qualifier in the intro, e.g. "Docker images are currently available for IceTray-based experiments (IceCube & P-ONE); KM3NeT users should install from source for now"?


Docker & Apptainer Images

@christianlocatelli christianlocatelli Jul 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know how familiar people in the community are with Docker/Apptainer. I personally never used containers before and would therefore have to look some things up before installing it.
In the Source installation section there is a link leading people to the Anaconda installation, so I thought it could be useful to provide at least a some links to the get started pages of Docker and Apptainer somewhere in this section. This is just a minor change but it leads ppl who are unfamiliar immediately to the most relevant pages.

Smth like:
(New to containers? See the get-started guides for Docker and Apptainer.)

=========================

We provide Docker images for |graphnet|\ GraphNeT — this is the recommended way to get started. The list of available images with standalone installations of GraphNeT can be found in DockerHub at https://hub.docker.com/r/rorsoe/graphnet/tags.

New images are created automatically when a new release is published, and when a new PR is merged to the main branch (latest). Each image comes in both GPU and CPU versions, but with a limited selection of pytorch versions. The Dockerfile for the standalone images is `here <https://github.com/graphnet-team/graphnet/blob/main/docker/standalone/Dockerfile>`_.

In compliment to standalone images, we also provide experiment-specific images for:

- `IceCube & P-ONE (IceTray+GraphNeT) <https://hub.docker.com/r/rorsoe/graphnet_icetray/tags>`_ which is built using this `Dockerfile <https://github.com/graphnet-team/graphnet/blob/main/docker/icetray/Dockerfile>`_.
- KM3NeT (km3io+GraphNeT) (Coming Soon)



Running Docker images as Apptainer environments
-----------------------------------------------
While Docker images require sudo-rights to run, they may be converted to Apptainer images and used as virtual environments - providing a convienient way to run |graphnet|\ GraphNeT without sudo-rights or the need to install it on your system. This is the standard path on HPC clusters.

To run one of the Docker images as a Apptainer environment, you can use the following command:

.. code-block:: bash

apptainer exec --cleanenv --env PYTHONNOUSERSITE=1 --env PYTHONPATH= docker://<path_to_image> bash

where <path_to_image> is the path to the image you want to use from the DockerHub. For example, if `rorsoe/graphnet:graphnet-1.8.0-cu126-torch26-ubuntu-22.04` is chosen, an image with GraphNeT 1.8.0 + PyTorch 2.6.0 + CUDA 12.6 installed will open. The additional arguments `--cleanenv --env PYTHONNOUSERSITE=1 --env PYTHONPATH=` ensure that the environment is not contaminated with any other packages that may be installed on your system.

To run one of the images with IceTray+GraphNeT as a Apptainer environment, you can for example use the following command:

.. code-block:: bash

apptainer exec --cleanenv --env PYTHONNOUSERSITE=1 --env PYTHONPATH= docker://rorsoe/graphnet_icetray:graphnet-1.8.0-cpu-torch26-icecube-icetray-icetray-devel-v1.13.0-ubuntu22.04-2025-02-12 bash

which opens an image with a CPU-installation of GraphNeT 1.8.0 + PyTorch v2.6.0 + IceTray v1.13.0 installed and ready to use. You can replace the image path with the one you want to use from the DockerHub.


Installing From Source

@christianlocatelli christianlocatelli Jul 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe here you could emphasize that this option is the recommended one for contributors.
"Installing From Source (for development, or if Docker/Apptainer isn't available)"

======================

If the Docker/Apptainer images above do not fit your use case — for example, you need a writable, editable install for development, or you cannot run a container runtime on your system — you can install |graphnet|\ GraphNeT from source.

We recommend installing |graphnet|\ GraphNeT in a separate environment, e.g. using a Python virtual environment or Anaconda (see details on installation `here <https://www.anaconda.com/products/individual>`_).
With conda installed, you can create a fresh environment like so

Expand All @@ -20,10 +59,10 @@ With conda installed, you can create a fresh environment like so
pip install --upgrade setuptools packaging

# Verify that only wheel, packaging and setuptools are installed
pip list
pip list

# Now you're ready to proceed with the installation


.. raw:: html
:file: quick-start.html
Expand All @@ -39,9 +78,7 @@ Below are some examples of how to install |graphnet|\ GraphNeT into experiment-s

IceTray (IceCube & P-ONE)
~~~~~~~~~~~~~~~~~~~~~~~~~~
While |graphnet|\ GraphNeT can be installed into existing IceTray environments that is either built from source or distributed through CVMFS, we highly recommend to instead use our existing Docker images that contain both IceTray and GraphNeT. These images are created by installing GraphNeT into public Docker images from the IceCube Collaboration.

Details on how to run these images as Apptainer environments are provided in the `Docker & Apptainer Images`_ section.
For IceTray-based workflows we strongly recommend the `IceCube & P-ONE (IceTray+GraphNeT) <https://hub.docker.com/r/rorsoe/graphnet_icetray/tags>`_ Docker images covered in the section above — they bundle a known-good IceTray + GraphNeT combination and avoid the version-pinning issues that come with installing GraphNeT into an existing IceTray environment.

For users who prefer to install |graphnet|\ GraphNeT directly into a CVMFS environment rather than using Docker/Apptainer images, you can follow the steps below. This example uses PyTorch 2.7.0 (CPU) — adjust the PyTorch version and extras according to the compatibility matrix above.

Expand Down Expand Up @@ -117,38 +154,4 @@ Downgrade setuptools for compatibility between km3io and GraphNeT.

pip3 install --force-reinstall setuptools==70.3.0
pip3 install km3io==1.2.0


Docker & Apptainer Images
=========================

We provide Docker images for |graphnet|\ GraphNeT. The list of available Docker images with standalone installations of GraphNeT can be found in DockerHub at https://hub.docker.com/r/rorsoe/graphnet/tags.

New images are created automatically when a new release is published, and when a new PR is merged to the main branch (latest). Each image comes in both GPU and CPU versions, but with a limited selection of pytorch versions. The Dockerfile for the standalone images is `here <https://github.com/graphnet-team/graphnet/blob/main/docker/standalone/Dockerfile>`_.

In compliment to standalone images, we also provide experiment-specific images for:

- `IceCube & P-ONE (IceTray+GraphNeT) <https://hub.docker.com/r/rorsoe/graphnet_icetray/tags>`_ which is built using this `Dockerfile <https://github.com/graphnet-team/graphnet/blob/main/docker/icetray/Dockerfile>`_.
- KM3NeT (km3io+GraphNeT) (Coming Soon)



Running Docker images as Apptainer environments
-----------------------------------------------
While Docker images require sudo-rights to run, they may be converted to Apptainer images and used as virtual environments - providing a convienient way to run |graphnet|\ GraphNeT without sudo-rights or the need to install it on your system.

To run one of the Docker images as a Apptainer environment, you can use the following command:

.. code-block:: bash

apptainer exec --cleanenv --env PYTHONNOUSERSITE=1 --env PYTHONPATH= docker://<path_to_image> bash

where <path_to_image> is the path to the image you want to use from the DockerHub. For example, if `rorsoe/graphnet:graphnet-1.8.0-cu126-torch26-ubuntu-22.04` is chosen, an image with GraphNeT 1.8.0 + PyTorch 2.6.0 + CUDA 12.6 installed will open. The additional arguments `--cleanenv --env PYTHONNOUSERSITE=1 --env PYTHONPATH=` ensure that the environment is not contaminated with any other packages that may be installed on your system.

To run one of the images with IceTray+GraphNeT as a Apptainer environment, you can for example use the following command:

.. code-block:: bash

apptainer exec --cleanenv --env PYTHONNOUSERSITE=1 --env PYTHONPATH= docker://rorsoe/graphnet_icetray:graphnet-1.8.0-cpu-torch26-icecube-icetray-icetray-devel-v1.13.0-ubuntu22.04-2025-02-12 bash

which opens an image with a CPU-installation of GraphNeT 1.8.0 + PyTorch v2.6.0 + IceTray v1.13.0 installed and ready to use. You can replace the image path with the one you want to use from the DockerHub.
Loading