Installation de Dagger et premier pipeline Python

Ce guide vous permet d’installer Dagger et d’exécuter votre premier pipeline Python en 15 minutes. Vous allez créer un projet minimal, initialiser Dagger et lancer deux fonctions : une qui affiche un message et une qui recherche du texte dans vos fichiers sources.

Prérequis : Docker (ou Podman) installé et un terminal Linux ou macOS.

Qu’est-ce qu’on va faire ?

À la fin de ce guide, vous aurez :

1. Dagger CLI installé (version 0.19.11)
2. Un projet Python minimal avec du code source
3. Un module Dagger initialisé avec le SDK Python
4. Deux fonctions pipeline testées et fonctionnelles

Pourquoi installer Dagger localement ?

Contrairement aux CI traditionnelles où vous devez pousser votre code pour tester un pipeline, Dagger vous permet d’exécuter vos pipelines directement sur votre machine. C’est le principe “local-first” :

Approche	CI traditionnelle	Dagger
Test d’un pipeline	commit → push → attendre → lire les logs	exécuter directement
Temps de feedback	2-10 minutes	quelques secondes
Debug	ajouter des echo partout	utiliser votre IDE
Reproductibilité	”ça marche en CI”	identique partout

Glissez pour voir

Prérequis

Avant de commencer, vérifiez que vous avez :

1. Docker ou Podman fonctionnel

   docker run hello-world

   Si vous utilisez Podman, activez le socket de compatibilité :

   systemctl --user start podman.socket

2. Python 3.10 ou supérieur

   python3 --version
   # Python 3.10.x ou supérieur

3. Un terminal avec accès sudo (pour l’installation)

Installer Dagger CLI

Linux

1. Téléchargez la dernière version stable

   cd /tmp
   wget https://github.com/dagger/dagger/releases/download/v0.19.11/dagger_v0.19.11_linux_amd64.tar.gz

2. Extrayez et installez

   tar xzf dagger_v0.19.11_linux_amd64.tar.gz
   sudo mv dagger /usr/local/bin/
   rm dagger_v0.19.11_linux_amd64.tar.gz

3. Vérifiez l’installation

   dagger version

   Résultat attendu :

   dagger v0.19.11 (image://registry.dagger.io/engine:v0.19.11) linux/amd64

macOS

1. Installez via Homebrew

   brew install dagger/tap/dagger

2. Vérifiez l’installation

   dagger version

   Résultat attendu :

   dagger v0.19.11 (image://registry.dagger.io/engine:v0.19.11) darwin/arm64

Première exécution

La première fois que vous lancez une commande Dagger, l’Engine télécharge son image Docker (~200 Mo). C’est normal et ne se produit qu’une fois.

Configurer l’autocomplétion (optionnel)

L’autocomplétion facilite la découverte des commandes et options.

Pour Zsh :

mkdir -p ~/.zsh/completions
dagger completion zsh > ~/.zsh/completions/_dagger
echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
source ~/.zshrc

Pour Bash :

mkdir -p ~/.bash/completions
dagger completion bash > ~/.bash/completions/_dagger
echo 'source ~/.bash/completions/_dagger' >> ~/.bashrc
source ~/.bashrc

Créer un projet Python minimal

Avant d’initialiser Dagger, créons un projet Python simple sur lequel travailler. Ce projet servira de base pour tous les labs du Volet 1.

1. Créez la structure du projet

   mkdir -p hello-dagger/src/hello_dagger
   cd hello-dagger

2. Créez le fichier pyproject.toml

   pyproject.toml

   [project]
   name = "hello-dagger"
   version = "0.1.0"
   description = "Projet minimal pour apprendre Dagger"
   requires-python = ">=3.10"
   readme = "README.md"
   
   [build-system]
   requires = ["hatchling"]
   build-backend = "hatchling.build"

3. Créez le fichier __init__.py

   src/hello_dagger/__init__.py

   """Hello Dagger - Projet minimal pour apprendre Dagger."""
   
   __version__ = "0.1.0"

4. Créez le fichier main.py

   src/hello_dagger/main.py

   """Point d'entrée de l'application Hello Dagger."""
   
   
   def greet(name: str = "World") -> str:
       """Retourne un message de salutation.
   
       Args:
           name: Le nom à saluer (défaut: "World")
   
       Returns:
           Message de salutation formaté
       """
       return f"Hello, {name}!"
   
   
   def main() -> None:
       """Fonction principale."""
       print(greet("Dagger"))
   
   
   if __name__ == "__main__":
       main()

Structure finale :

• Répertoirehello-dagger/

  • pyproject.toml
  • Répertoiresrc/

    • Répertoirehello_dagger/

      • __init__.py
      • main.py

Vérification :

python3 src/hello_dagger/main.py

Résultat attendu :

Hello, Dagger!

Initialiser un module Dagger

Un “module” Dagger est un ensemble de fonctions pipeline écrites dans un SDK (Python, Go, TypeScript). La commande dagger init génère la structure nécessaire.

1. Depuis la racine du projet, initialisez Dagger avec le SDK Python

   dagger init --sdk=python --source=./dagger

   Ce que fait cette commande :

   • Crée un fichier dagger.json (configuration du module)
   • Crée un dossier dagger/ avec le code Python du pipeline
   • Génère un fichier uv.lock (dépendances)

   Temps de la première initialisation

   La première fois, Dagger télécharge le SDK Python et ses dépendances. Cela peut prendre 30-60 secondes. Les initialisations suivantes sont quasi-instantanées.

2. Explorez la structure générée

   • Répertoirehello-dagger/

     • dagger.json
     • Répertoiredagger/

       • pyproject.toml
       • Répertoiresrc/

         • Répertoirehello_dagger/

           • main.py
       • Répertoiresdk/

         • …
       • uv.lock
     • pyproject.toml
     • Répertoiresrc/

       • Répertoirehello_dagger/

         • __init__.py
         • main.py

3. Regardez le code généré

   cat dagger/src/hello_dagger/main.py

   import dagger
   from dagger import dag, function, object_type
   
   
   @object_type
   class HelloDagger:
       @function
       def container_echo(self, string_arg: str) -> dagger.Container:
           """Returns a container that echoes whatever string argument is provided"""
           return dag.container().from_("alpine:latest").with_exec(["echo", string_arg])
   
       @function
       async def grep_dir(self, directory_arg: dagger.Directory, pattern: str) -> str:
           """Returns lines that match a pattern in the files of the provided Directory"""
           return await (
               dag.container()
               .from_("alpine:latest")
               .with_mounted_directory("/mnt", directory_arg)
               .with_workdir("/mnt")
               .with_exec(["grep", "-R", pattern, "."])
               .stdout()
           )

Que signifie ce code ?

Élément	Rôle
@object_type	Définit une classe comme module Dagger
@function	Expose une méthode comme fonction appelable via CLI
dag.container()	Crée un nouveau conteneur
.from_("alpine:latest")	Utilise l’image Alpine comme base
.with_exec([...])	Exécute une commande dans le conteneur
.stdout()	Récupère la sortie standard

Glissez pour voir

Exécuter vos premières fonctions

Maintenant que le module est initialisé, testons les deux fonctions générées.

Fonction 1 : container-echo

Cette fonction crée un conteneur Alpine et exécute echo avec l’argument fourni.

dagger call container-echo --string-arg HelloDagger stdout

Explication de la commande :

• dagger call : appelle une fonction du module
• container-echo : nom de la fonction (kebab-case automatique)
• --string-arg HelloDagger : argument de la fonction
• stdout : récupère la sortie standard du conteneur

Résultat attendu :

✔ connect 0.3s
✔ load module: . 0.3s
✔ parsing command line arguments 0.0s

✔ helloWorld: HelloDagger! 0.0s
✔ .containerEcho(stringArg: "HelloDagger"): Container! 0.2s
✔ .stdout: String! 0.2s

HelloDagger

Cache en action

Relancez la même commande : elle s’exécute en quelques millisecondes car Dagger cache le résultat.

Fonction 2 : grep-dir

Cette fonction monte un répertoire dans un conteneur et recherche un pattern dans les fichiers.

dagger call grep-dir --directory-arg=src --pattern=Hello

Résultat attendu :

✔ connect 0.2s
✔ load module: . 0.4s
✔ parsing command line arguments 0.0s

✔ helloWorld: HelloDagger! 0.0s
✔ .grepDir(
  ┆ directoryArg: Address.directory: Directory!
  ┆ pattern: "Hello"
  ): String! 1.5s

./hello_dagger/__init__.py:"""Hello Dagger - Projet minimal pour apprendre Dagger."""
./hello_dagger/main.py:"""Point d'entrée de l'application Hello Dagger."""
./hello_dagger/main.py:    return f"Hello, {name}!"

La fonction a trouvé toutes les occurrences de “Hello” dans vos fichiers Python.

Comprendre ce qui s’est passé

Récapitulons ce qui se passe quand vous exécutez dagger call :

1. Connexion à l’Engine : Dagger se connecte au daemon Docker/Podman
2. Chargement du module : le code Python de dagger/ est interprété
3. Parsing des arguments : les options CLI sont validées
4. Exécution : un conteneur est créé et la commande s’exécute
5. Cache : le résultat est stocké pour réutilisation

Tout cela se passe localement sur votre machine. Quand vous exécuterez le même pipeline en CI (GitLab, GitHub Actions…), il produira exactement le même résultat.

Dépannage

”dagger: command not found”

Le binaire n’est pas dans votre PATH.

# Vérifiez où il est installé
ls -la /usr/local/bin/dagger

# Si absent, refaites l'installation
# ou ajoutez le chemin à votre PATH
export PATH=$PATH:/usr/local/bin

”Cannot connect to the Docker daemon”

Docker n’est pas démarré.

# Linux avec systemd
sudo systemctl start docker

# Vérifiez que docker fonctionne
docker run hello-world

”permission denied while trying to connect”

Votre utilisateur n’a pas les droits Docker.

# Ajoutez-vous au groupe docker
sudo usermod -aG docker $USER

# Déconnectez-vous et reconnectez-vous
# ou utilisez newgrp
newgrp docker

Premier appel très lent (30-60s)

C’est normal lors de la première exécution. Dagger télécharge :

• L’image de l’Engine (~200 Mo)
• Le SDK Python et ses dépendances
• L’image de base (alpine:latest)

Les exécutions suivantes utilisent le cache et sont quasi-instantanées.

À retenir

• Dagger CLI s’installe en quelques secondes (télécharger + déplacer)
• dagger init --sdk=python génère un module avec des fonctions d’exemple
• dagger call exécute une fonction pipeline depuis le terminal
• Le cache accélère drastiquement les exécutions répétées
• Local-first : debug rapide sans pousser de code

Prochaines étapes

Maintenant que Dagger est installé et fonctionnel, vous pouvez :

• Connexion, async et erreurs — Comprendre le cycle de vie async et gérer les erreurs
• Module 4 : Container API — Maîtriser la création de conteneurs, l’exécution de commandes et la gestion des variables d’environnement (à venir)

×

📖 Voir la documentation →