volume mounts (Docker)

Journaux liées à cette note :

Est-ce qu'une fonction Open WebUI peut importer une autre fonction Open WebUI ? #python

J'ai essayé de comprendre si une fonction Open WebUI pouvait importer le code d'une autre fonction Open WebUI.
La réponse est non. Je vais tenter dans cette note d'expliquer pourquoi.

(j'ai aussi publié une version de cette note en anglais dans la section "discussions" de Open WebUI)

Open WebUI propose de méthode pour créer ou mettre à jour une fonction Open WebUI sur une instance en production : via l'interface web d'administration, ou via l'API REST.

Une instance production fait référence à Open WebUI hébergé sur une Virtual machine ou un Cluster Kubernetes, par opposition à une instance locale lancée en mode développement.

Dans un premier temps, j'ai essayé d'importer dans Open WebUI les deux fichiers suivants :

# utils.py
def add(a, b):
    return a + b

# hello_world.py
from pydantic import BaseModel, Field

from .utils import add

class Pipe:
    class Valves(BaseModel):
        pass

    def __init__(self):
        self.valves = self.Valves()

    def pipe(self, body: dict):
        print("body", body)

        return f"Hello, World! {add(1, 2)}"

Le fichier hello_world.py contient un import de utils.add implémenté dans le premier fichier.

L'importation du premier fichier est refusée par Open WebUI parce que class Pipe: est absent de utils.py.

J'ai ensuite trompé Open WebUI en ajoutant une classe Pipe fictive das le fichier utils.py et l'importation a réussi.

Ensuite l'import de hello_world.py a échoué parce que Open WebUI n'arrive pas a effectué l'import from .utils import add. J'ai ensuite effectué plusieurs tentatives d'import absolut, par exemple from open_webui.utils import add… mais sans succès.

J'ai pris un peu de temps pour étudier l'implémentation d'Open WebUI et j'ai identifié cette section de code :

module_name = f"tool_{tool_id}"
module = types.ModuleType(module_name)
sys.modules[module_name] = module

Ce code permet à Open WebUI de charger dynamiquement le code source des modules qui sont stockés dans la base de données.

Un esprit tordu pourrait en pratique importer une fonction chargé dynamiquement dans un autre module dynamique, par exemple :

from tool_utils import add

Mais cette méthode ne correspond pas à l'usage normal d'Open WebUI.

Pour implémenter des fonctions "modulaires", Open WebUI conseille d'utiliser la fonctionnalité "Pipelines" :

Welcome to Pipelines, an Open WebUI initiative. Pipelines bring modular, customizable workflows to any UI client supporting OpenAI API specs – and much more! Easily extend functionalities, integrate unique logic, and create dynamic workflows with just a few lines of code.

source

Pour les personnes qui souhaitent vraiment effectuer des imports dans des fonctions Open WebUI sans utiliser la fonction Pipelines, il existe tout de même une solution que j'ai implémentée dans la branche test-if-openwebui-function-support-import.

Voici le contenu de /functions/hello_world.py :

from pydantic import BaseModel, Field

from open_webui.shared.utils import add

class Pipe:
    class Valves(BaseModel):
        pass

    def __init__(self):
        self.valves = self.Valves()

    def pipe(self, body: dict):
        print("body", body)

        return f"Hello, World! {add(1, 2)}"

Le contenu de /shared/utils.py

def add(a, b):
    return a + b

Pour rendre accessible /shared/utils.py dans l'instance d'Open WebUI lancé loculement, j'ai configuré de volume mounts suivante dans mon /docker-compose.yml :

  openwebui:
    image: ghcr.io/open-webui/open-webui:0.6.15
    restart: unless-stopped
    volumes:
      - ./shared/:/app/backend/open_webui/shared/
    ports:
      - "3000:8080"

Ensuite, si je souhaite pouvoir déployer en production cette fonction Open WebUI et le module utils.py, il sera nécessaire de build une image Docker customisé d'Open WebUI pour y inclure le fichier /shared/utils.py.

Cette méthode peut fonctionner, mais cela reste un "hack" non conseillé. Il est préférable d'utiliser la méthode "Pipelines".

Journal du lundi 09 décembre 2024 à 15:50 #dev-kit, #docker

J'utilise la fonctionnalité Docker volume mounts dans tous mes projets depuis septembre 2015.

Généralement, sous la forme suivante :

services:
  postgres:
    image: postgres:17
    ...
	volumes:
      - ./volumes/postgres/:/var/lib/postgresql/data/

D'après mes recherches, la fonctionnalité volumes mounts a été introduite dans la version 0.5.0 en juillet 2013.

À cette époque, je crois me souvenir que Docker permettait aussi de créer des volumes anonymes. Je n'ai jamais apprécié les volumes anonymes, car lorsqu'un conteneur était supprimé, il devenait compliqué de retrouver le volume associé.
À cette époque, Docker était nouveau et j'avais très peur de perdre des données, par exemple, les volumes d'une instance PostgreSQL.

J'ai donc décidé qu'il était préférable de renoncer aux volumes anonymes et d'opter systématiquement pour des volume mounts.

Ensuite, peut-être en janvier 2016, Docker a introduit les named volumes, qui permettent de créer des volumes avec des noms précis, par exemple :

services:
  postgres:
    image: postgres:17
    ...
	volumes:
      - postgres:/var/lib/postgresql/data/

volumes:
  postgres:
    name: postgres

$ docker volume ls
DRIVER    VOLUME NAME
local     postgres

Ce volume est physiquement stocké dans le dossier /var/lib/docker/volumes/postgres/_data.

Depuis, j'ai toujours préféré les volumes mounts aux named volumes pour les raisons pratiques suivantes :

  • Travaillant souvent sur plusieurs projets, j'utilise les volume mounts pour éviter les collisions. Lorsque j'ai essayé les named volumes, une question s'est posée : quel nom attribuer aux volumes PostgreSQL ? « postgres » ? Mais alors, quel nom donner au volume PostgreSQL dans le projet B ? Avec les volume mounts, ce problème ne se pose pas.
  • J'apprécie de savoir qu'en supprimant un projet avec rm -rf ~/git/github.com/stephan-klein/foobar/, cette commande effacera non seulement l'intégralité du projet, mais également ses volumes Docker.
  • Avec les mounted volume, je peux facilement consulter le contenu des volumes. Je n'ai pas besoin d'utiliser docker volume inspect pour trouver le chemin du volume.

La stratégie que j'ai choisie basée sur volumes mounts a quelques inconvénients :

  • Le owner du dossier volumes/, situé dans le répertoire du projet, est root. Cela entraîne fréquemment des problèmes de permissions, par exemple lors de l'exécution des scripts de linter dans le dossier du projet. Pour supprimer le projet, je dois donc utiliser sudo. Je précise que ce problème n'existe pas sous MacOS. Je pense que ce problème pourrait être contourné sous Linux en utilisant podman.
  • La commande docker compose down -v ne détruit pas les volumes.

Je suis pleinement conscient que ma méthode basée sur les volume mounts est minoritaire. En revanche, j'observe qu'une grande majorité des développeurs privilégie l'utilisation des named volumes.

Par exemple, cet été, un collègue a repris l'un de mes projets, et l'une des premières choses qu'il a faites a été de migrer ma configuration de volume mounts vers des named volumes pour résoudre un problème de permissions lié à Prettier, eslint ou Jest. En effet, la fonctionnalité ignore de ces outils ne fonctionne pas si NodeJS n'a pas les droits d'accès à un dossier du projet 😔.

Aujourd'hui, je me suis lancé dans la recherche d'une solution me permettant d'utiliser des named volumes tout en évitant les problèmes de collision entre projets.

Je pense que j'ai trouvé une solution satisfaisante 🙂.

Je l'ai décrite et testée dans le repository docker-named-volume-playground.

Ce repository d'exemple contient 2 projets distincts, nommés project_a et project_b.
J'ai instancié deux fois chacun de ces projets. Voici la liste des dossiers :

$ tree
.
├── project_a_instance_1
│   ├── docker-compose.yml
│   └── .envrc
├── project_a_instance_2
│   ├── docker-compose.yml
│   └── .envrc
├── project_b_instance_1
│   ├── docker-compose.yml
│   └── .envrc
├── project_b_instance_2
│   ├── docker-compose.yml
│   └── .envrc
└── README.md

Ce repository illustre l'organisation de plusieurs instances de différents projets sur la workstation du développeur.
Il ne doit pas être utilisé tel quel comme base pour un projet.
Par exemple, le "vrai" repository du projet projet_a se limiterait aux fichiers suivants : docker-compose.yml et .envrc.

Voici le contenu d'un de ces fichiers .envrc :

export PROJECT_NAME="project_a"
export INSTANCE_ID=$(pwd | shasum -a 1 | awk '{print $1}' | cut -c 1-12) # Used to define docker volume path
export COMPOSE_PROJECT_NAME=${PROJECT_NAME}_${INSTANCE_ID}

L'astuce que j'utilise est au niveau de INSTANCE_ID. Cet identifiant est généré de telle manière qu'il soit unique pour chaque instance de projet installée sur la workstation du développeur.
J'ai choisi de générer cet identifiant à partir du chemin complet vers le dossier de l'instance, je le passe dans la commande shasum et je garde les 12 premiers caractères.

J'utilise ensuite la valeur de COMPOSE_PROJECT_NAME dans le docker-compose.yml pour nommer le named volume :

services:
  postgres:
    image: postgres:17
    environment:
      POSTGRES_USER: postgres
      POSTGRES_DB: postgres
      POSTGRES_PASSWORD: password
    ports:
      - 5432
    volumes:
      - postgres:/var/lib/postgresql/data/
    healthcheck:
      test: ["CMD", "sh", "-c", "pg_isready -U $$POSTGRES_USER -h $$(hostname -i)"]
      interval: 10s
      start_period: 30s

volumes:
  postgres:
     name: ${COMPOSE_PROJECT_NAME}_postgres

Exemples de valeurs générées pour l'instance installée dans /home/stephane/git/github.com/stephane-klein/docker-named-volume-playground/project_a_instance_1 :

  • INSTANCE_ID=d4cfab7403e2
  • COMPOSE_PROJECT_NAME=project_a_d4cfab7403e2
  • Nom du container postgresql : project_a_d4cfab7403e2-postgres-1
  • Nom du volume postgresql : project_a_a04e7305aa09_postgres

Conclusion

Cette méthode me permet de suivre une pratique plus mainstream — utiliser les named volumes Docker — tout en évitant la collision des noms de volumes.

Je suis conscient que ce billet est un peu long pour expliquer quelque chose de simple, mais je tenais à partager l'historique de ma démarche.

Je pense que je vais dorénavant utiliser cette méthode pour tous mes nouveaux projets.

20224-12-10 11h27 : Je tiens à préciser qu'avec la configuration suivante :

services:
  postgres:
    image: postgres:17
    ...
	volumes:
      - postgres:/var/lib/postgresql/data/

volumes:
  postgres:

Quand le nom du volume postgres n'est pas défini, docker-compose le nomme sous la forme ${COMPOSE_PROJECT_NAME}_postgres. Si le projet est stocké dans le dossier foobar, alors le volume sera nommé foobar_postgres.

$ docker volume ls
DRIVER    VOLUME NAME
local     foobar_postgres