.. _itwinai_container_usage:

Using itwinai Container Images
==============================

itwinai provides pre-built container images to facilitate the deployment and scaling of machine
learning applications. These containers are built at each release and are available in two
locations:

- **Docker images**: Hosted on GitHub Container Registry (GHCR) under ``ghcr.io/intertwin-eu``
- **Singularity images**: Available on Harbor at ``registry.egi.eu/dev.intertwin.eu``

These images provide a convenient base for users to build their applications on top of a
pre-configured environment optimized for high-performance computing (HPC) and deep learning
workflows.

Available Container Images
--------------------------

Three types of container flavors are available:

- **torch-slim**: Includes Horovod and DeepSpeed, tested on HPC (currently Vega)
- **torch-skinny**: A minimal installation with a significantly reduced image size
- **jlab-slim**: Designed for JupyterLab single-user mode, supports offloading to HPC via interLink

Container Registries
--------------------

Docker Containers (GHCR)
~~~~~~~~~~~~~~~~~~~~~~~~

Docker images are hosted on GitHub Container Registry (GHCR) under two repositories:

- **Release Images**: ``ghcr.io/intertwin-eu/itwinai``
- **Development Images**: ``ghcr.io/intertwin-eu/itwinai-dev``

  - Includes images built from pushes to the ``main`` branch.

To use these containers as a base for your application, reference them in your ``Dockerfile``
with the ``FROM`` directive.

All the containers under ``ghcr.io/intertwin-eu/itwinai`` image, whose tag matches ``*-latest``
will be made available through CVMFS via `Unpacker <https://gitlab.cern.ch/unpacked/sync>`_.

Singularity Containers (Harbor)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Singularity images are stored on Harbor (``registry.egi.eu/dev.intertwin.eu``) and are directly
pullable on HPC systems without conversion.

For JupyterHub integration, use the following URI format to launch JupyterLab single-user
containers::

    oras://registry.egi.eu/dev.intertwin.eu/itwinai:TAG

For example::

    oras://registry.egi.eu/dev.intertwin.eu/itwinai:jlab-slim-latest

Building Applications on Top of itwinai Containers
--------------------------------------------------

Users can build their applications by creating a ``Dockerfile`` that extends an ``itwinai``
container image. Below is an example ``Dockerfile`` using ``torch-slim-latest`` as a base
image:

.. code-block:: dockerfile

    FROM ghcr.io/intertwin-eu/itwinai:torch-slim-latest

    # Set working directory
    WORKDIR /app

    # Copy application dependencies
    COPY requirements.txt ./

    # Install dependencies
    RUN pip install --no-cache-dir -r requirements.txt

    # Copy application code
    COPY . .

    # Set entrypoint
    CMD ["python", "main.py"]

This example assumes that:

- The application dependencies are listed in ``requirements.txt``
- The application code (including ``main.py``) is copied into the container
- The application is executed by running ``python main.py``

If you want to create a JupyterLab container you can replace
``ghcr.io/intertwin-eu/itwinai:jlab-slim-latest`` in the ``FROM`` clause above.

By using ``itwinai`` container images, users can focus on their application logic while
leveraging a pre-configured environment optimized for HPC and deep learning workflows.