Démarrer rapidement avec Docker Compose¶

Cette démarche rapide vous montre comment configurer Flower en utilisant Docker Compose à partir d’une seule commande, vous permettant de vous concentrer sur le développement de votre application sans vous soucier de l’infrastructure sous-jacente.

Vous apprendrez également comment activer facilement TLS et persister l’état d’application localement, vous donnant la liberté de choisir la configuration qui convient le mieux à vos besoins du projet.

Prérequis¶

Avant de commencer, assurez-vous que :

Le flwr CLI est installed localement.
Le daemon Docker est en cours d’exécution.
Docker Compose V2 est installed.

Étape 1 : Configuration¶

Cloner le répertoire Compose Docker :

$ git clone --depth=1 --branch v1.31.0 https://github.com/flwrlabs/flower.git _tmp \
            && mv _tmp/framework/docker/complete . \
            && rm -rf _tmp && cd complete

Créer une nouvelle application Flower (PyTorch) :
```
$ flwr new @flwrlabs/quickstart-pytorch
```
Exporter le chemin du projet créé récemment. Le chemin doit être relatif au emplacement des fichiers Docker Compose :
```
$ export PROJECT_DIR=quickstart-pytorch
```
Définir la variable d’environnement PROJECT_DIR aide Compose à localiser le fichier pyproject.toml, permettant ainsi l’installation des dépendances dans les images ServerApp et ClientApp correctement.

Étape 2 : Lancer Flower en mode non sécurisé¶

Pour commencer, démarrez Flower avec la configuration de base la plus simple. Dans cette configuration, Flower sera exécuté sans TLS et sans persister l’état.

Note

Sans TLS, les données transmises entre les services restent non chiffrées. Utilisez-le uniquement à des fins de développement.

Pour les cas d’utilisation orientés vers la production, enable TLS pour une transmission sécurisée des données.

Ouvrez votre terminal et exécutez :

$ docker compose up --build -d

Étape 3 : Lancer le projet Quickstart¶

Maintenant que les services Flower ont été démarrés via Docker Compose, il est temps de lancer l’exemple de démonstration rapide.

Pour vous assurer que le flwr CLI se connecte au SuperLink, vous devez spécifier la connexion SuperLink dans votre fichier de configuration Flower.

Trouvez le fichier de configuration TOML Flower sur votre machine. Ce fichier est automatiquement créé pour vous lorsque vous utilisez pour la première fois un Flower CLI commande. Utilisez flwr config list pour voir les connexions SuperLink disponibles ainsi que le chemin du fichier de configuration.
```
$ flwr config list

Flower Config file: /path/to/.flwr/config.toml
SuperLink connections:
  supergrid
  local (default)
```

Ajoutez les lignes suivantes au config.toml:

config.toml¶

[superlink.local-deployment]
address = "127.0.0.1:9093"
insecure = true

Exécutez l’exemple quickstart, suivez les journaux ServerApp et attendez que le résumé apparaisse:
```
$ flwr run quickstart-pytorch local-deployment --stream
```

Étape 4 : Mettre à jour l’application¶

Dans la prochaine étape, modifiez le code de l’application.

Par exemple, allez dans le fichier task.py du répertoire quickstart-pytorch/pytorchexample/ et ajoutez un appel print à la fonction get_weights:
quickstart-pytorch/pytorchexample/task.py¶
```
# ...
def get_weights(net):
    print("Get weights")
    return [val.cpu().numpy() for _, val in net.state_dict().items()]


# ...
```
Rebuilder et redémarrez les services.

Note

Si vous avez modifié les dépendances listées dans votre fichier pyproject.toml, il est essentiel de reconstruire les images.

Si vous n’avez fait aucun changement, vous pouvez sauter cette étape.

Exécutez la commande suivante pour recompiler et redémarrer les services :
```
$ docker compose up --build -d
```

Lancer l’exemple mis à jour de démonstration rapide :

$ flwr run quickstart-pytorch local-deployment --stream

Dans les journaux ServerApp, vous devriez trouver la ligne Get weights:

INFO :      Starting logstream for run_id `10386255862566726253`
INFO :      Starting Flower ServerApp
WARNING :   Option `--insecure` was set. Starting insecure HTTP channel to superlink:9091.
🎊 Successfully installed quickstart-pytorch to /app/.flwr/apps/flower.quickstart-pytorch.1.0.0.35361a47.
Get weights
INFO :      Starting Flower ServerApp, config: num_rounds=3, no round_timeout

Étape 5 : Persister l’état du SuperLink¶

Dans cette étape, les services Flower sont configurés pour persister l’état du service SuperLink, garantissant qu’il maintienne son état même après un redémarrage.

Note

Lorsque vous travaillez avec Compose sur Linux, il peut être nécessaire de créer le répertoire state en premier et de changer ses droits d’accès pour s’assurer des accès et permissions corrects.

Pour plus d’informations, consultez la page suivante : Conservation de l’État du SuperLink.

Exécutez la commande :
```
$ docker compose -f compose.yml -f with-state.yml up --build -d
```
Comprendre la commande
- docker compose: La commande Docker pour exécuter l’outil Compose Docker.
- -f compose.yml: Spécifiez le fichier YAML contenant les définitions de service de base Flower.
- -f with-state.yml: Spécifiez le chemin vers un fichier Compose supplémentaire Docker :
  
  contient la configuration pour persister l’état de SuperLink.
  
  Docker fusionne les fichiers Compose selon merging rules.
- --build: Rebuilder les images pour chaque service si elles n’existent pas déjà.
- -d: Détachez les conteneurs de la console et exécutez-les en arrière-plan.

Reexécutez le projet quickstart-pytorch:

$ flwr run quickstart-pytorch local-deployment --stream

Vérifiez le contenu du répertoire state:
```
$ ls state/
state.db
```
Vous devriez voir un fichier state.db dans le répertoire state. Si vous redémarrez le service, le fichier de state sera utilisé pour restaurer l’état à partir des données précédemment sauvegardées. Cela garantit que les données persistent même si les conteneurs sont arrêtés et relancés.

Étape 6 : Exécutez Flower avec TLS¶

Pour démontrer comment activer le TLS, générer des certificats auto-signés à l’aide du fichier certs.yml Compose.

Important

Utilisez ces certificats uniquement à des fins de développement.

Pour les environnements de production, utilisez un service comme Let’s Encrypt pour obtenir vos certificats.

Exécutez la commande :
```
$ docker compose -f certs.yml run --rm --build gen-certs
```

Ajoutez une nouvelle connexion SuperLink à votre fichier de configuration Flower :

config.toml¶

[superlink.local-deployment-tls]
address = "127.0.0.1:9093"
root-certificates = "/absolute/path/to/superlink-certificates/ca.crt"

Redémarrez les services avec TLS activé :

$ docker compose -f compose.yml -f with-tls.yml up --build -d

Reexécutez le projet quickstart-pytorch:

$ flwr run quickstart-pytorch local-deployment-tls --stream

Étape 7 : Ajoutez un autre SuperNode et ClientApp¶

Vous pouvez ajouter plus de SuperNodes et de ClientApps en commentant leurs définitions dans le fichier compose.yml :

compose.yml¶

  # other service definitions

  supernode-3:
    image: flwr/supernode:${FLWR_VERSION:-1.31.0}
    command:
      - --insecure
      - --superlink
      - superlink:9092
      - --clientappio-api-address
      - 0.0.0.0:9096
      - --isolation
      - process
      - --node-config
      - "partition-id=1 num-partitions=2"
    depends_on:
      - superlink

  superexec-clientapp-3:
    build:
      context: ${PROJECT_DIR:-.}
      dockerfile_inline: |
        FROM flwr/superexec:${FLWR_VERSION:-1.31.0}

        USER root
        RUN apt-get update \
            && apt-get -y --no-install-recommends install \
            build-essential \
            && rm -rf /var/lib/apt/lists/*
        USER app

        WORKDIR /app
        COPY --chown=app:app pyproject.toml .
        RUN sed -i 's/.*flwr\[simulation\].*//' pyproject.toml \
          && python -m pip install -U --no-cache-dir .

        ENTRYPOINT ["flower-superexec"]
    command:
      - --insecure
      - --plugin-type
      - clientapp
      - --appio-api-address
      - supernode-3:9096
    deploy:
      resources:
        limits:
          cpus: "2"
    stop_signal: SIGINT
    depends_on:
      - supernode-3

Si vous voulez également activer le TLS pour le nouveau SuperNode, décommentez la définition dans le fichier with-tls.yml :

with-tls.yml¶

  # other service definitions

  supernode-3:
    command:
      - --superlink
      - superlink:9092
      - --clientappio-api-address
      - 0.0.0.0:9096
      - --isolation
      - process
      - --node-config
      - "partition-id=1 num-partitions=2"
      - --root-certificates
      - certificates/superlink-ca.crt
    secrets:
      - source: superlink-ca-certfile
        target: /app/certificates/superlink-ca.crt

Redémarrez les services avec :

$ docker compose up --build -d
# or with TLS enabled
$ docker compose -f compose.yml -f with-tls.yml up --build -d

Étape 8 : Persister l’état de SuperLink et activer TLS¶

Pour exécuter Flower avec un état persistant de SuperLink et le TLS activé, une légère modification est requise dans le fichier with-state.yml :

Commentez les lignes 2-6 et décommentez les lignes 7-13 :

with-state.yml¶

  superlink:
    # command:
    # - --insecure
    # - --isolation
    # - process
    # - --database=state/state.db
    command:
      - --isolation
      - process
      - --ssl-ca-certfile=certificates/ca.crt
      - --ssl-certfile=certificates/server.pem
      - --ssl-keyfile=certificates/server.key
      - --database=state/state.db
    volumes:
      - ./state/:/app/state/:rw

Redémarrez les services :

$ docker compose -f compose.yml -f with-tls.yml -f with-state.yml up --build -d

Reexécutez le projet quickstart-pytorch:

$ flwr run quickstart-pytorch local-deployment-tls --stream

Étape 9 : Fusionner plusieurs fichiers Compose¶

Vous pouvez fusionner plusieurs fichiers Compose en un seul fichier. Par exemple, si vous souhaitez combiner la configuration de base avec la configuration TLS, exécutez la commande suivante :

$ docker compose -f compose.yml \
   -f with-tls.yml config --no-path-resolution > my_compose.yml

Cela fusionnera les contenus de compose.yml et with-tls.yml dans un nouveau fichier appelé my_compose.yml.

Étape 10 : Nettoyage¶

Supprimez tous les services et volumes :

$ docker compose down -v

Où aller ensuite ?¶

Exécuter les Exemples de Démarrage Rapide Flower avec Docker Compose