Kernels

Création et publication des kernels jupyter

Création d’un nouveau kernel

Il existe plusieurs façons de décrire un kernel Jupyter pour Gaia Data.

  1. (Recommandée) Utilisation d’un fichier conda-lock
  2. Utilisation d’un fichier conda-lock
  3. Utilisation d’un fichier Dockerfile
Warning

Quelle que soit la méthode utilisée, l’environnement conda doit contenir ipykernel pour être correctement utilisé.

Utilisation de conda-lock

Ceci est la méthode privilégiée car elle est la plus simple et garantit une bonne reproductibilité de l’environnement.

conda-lock est une libraire qui permet de générer un fichier lock pour les environnements conda.

# Avec un fichier environment.yml
conda-lock lock -f environment.yml -p linux-64

# Avec un fichier pyproject.toml
conda-lock lock -f pyproject.toml -c conda-forge -p linux-64

Arborescence :

jupyter-kernels/
└── my-kernel/
    ├── environment.yml # facultatif
    └── conda-lock.yml

Utilisation via un fichier environment.yml

Cette méthode n’est pas recommandée car elle ne garantit pas la bonne reproductibilité de votre environnement. Dans ce cas, le pipeline de construction du kernel générera le conda-lock à la volée.

Arborescence :

jupyter-kernels/
└── my-kernel/
    └── environment.yml

Utilisation de Dockerfile

Cette méthode pour les utilisateur·ices avancé·es qui ont besoin d’installer des librairies tierces non disponibles dans conda-forge, par exemple. Dans ce cas, le Dockerfile fournit est utilisé à la place de celui par défaut. Attention, l’image finale ne doit contenir que l’environnement conda.

Ex:

FROM mambaorg/micromamba:2.0.8 AS builder

USER root
RUN apt-get update && apt-get install curl libarchive

USER ${MAMBA_USER}
COPY --chown=${MAMBA_USER} ./conda-lock.yml /tmp/conda-lock.yml
RUN micromamba install conda-lock \
    && micromamba create -y --name my-kernel \
    && micromamba run conda-lock install --micromamba --name my-kernel /tmp/conda-lock.yml \
    && curl 'https://codeload.github.com/overmighty/i-use-arch-btw/zip/refs/heads/master' |bsdtar -xvf- \
    && mkdir build && cd build \
    && micromamba run -n my-kernel cmake  -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF .. \
    && micromamba run -n my-kernel cmake  --build . \
    && micromamba run -n my-kernel cmake  --install . \
    && micromamba clean --all --yes

FROM scratch

COPY --from=builder /opt/conda/envs/my-kernel /

Arborescence :

jupyter-kernels/
└── my-kernel/
    ├── Dockerfile
    ├── environment.yml # facultatif
    └── conda-lock.yml

Documentation d’un nouveau kernel

En plus de la description des dépendences du kernel, il est recommandé de fournir :

  • un fichier _description.qmd contenant une brève description de l’environnement et des cas d’usages associés ;

  • un ou plusieurs notebooks au format ipynb, dans un répertoire notebooks. Ceux-ci doivent pouvoir être exécutés de manière automatique, par exemple avec la commande suivante :

    jupyter nbconvert --execute --to notebook nb.ipynb

Arborescence:

jupyter-kernels/
└── my-kernel/
    ├── environment.yml # facultatif
    ├── conda-lock.yml
    ├── _description.qmd # facultatif
    └── notebooks
        ├── nb-1.ipynb
        └── nb-2.ipynb

Publication d’un nouveau kernel

La demande d’ajout passe par une Merge Request sur le projet Jupyter Kernels Gaia Data.