Exigences de Potato pour votre équipe informatique

Potato est une application web auto-hébergée pour les études d'annotation. Un processus Potato sert une étude, garde chaque annotation dans des fichiers et des bases SQLite à l'intérieur du dossier de l'étude, et a besoin d'un proxy inverse devant le processus pour le HTTPS. Une installation par défaut n'envoie rien à des services extérieurs, et les données ne quittent le serveur que par les fonctionnalités que la configuration de l'étude active.

Cette page est écrite pour les personnes qui exploitent des serveurs dans une université, un hôpital ou une entreprise. Un chercheur qui souhaite faire héberger une étude peut envoyer la page telle quelle, avec le dossier du projet et les réponses listées dans la section suivante. Mettre votre étude Potato en ligne couvre les voies qu'un chercheur peut suivre sans équipe informatique.

Informations de l'équipe de recherche

L'équipe de recherche envoie le dossier du projet, que le Study Designer exporte sous le nom Télécharger le projet (.zip). Le dossier contient config.yaml, la configuration de l'étude, et les fichiers de données que la configuration nomme. Avec le dossier, l'équipe de recherche répond à ces questions :

• Combien d'annotateurs participent, et les annotateurs se connectent-ils avec des comptes institutionnels ou avec des noms d'utilisateur que le chercheur liste ?
• Quand l'étude commence-t-elle et se termine-t-elle ?
• Les items ou les réponses contiennent-ils des informations personnelles ou sensibles, et sous quelle approbation éthique l'étude se déroule-t-elle ?
• La configuration utilise-t-elle des fonctionnalités d'IA qui envoient des items à un fournisseur de modèles ? Des blocs comme ai_support, chat_support et solo_mode dans config.yaml signalent de telles fonctionnalités.

Logiciel

Potato est une application web Python construite sur Flask. L'installation la plus simple est l'image Docker publiée, ghcr.io/davidjurgens/potato, construite pour linux/amd64 et linux/arm64. L'image pèse environ 900 Mo, exécute Python 3.11 sous gunicorn avec l'utilisateur sans privilèges potato (uid 1000) et écoute sur le port 7860. Le dossier du projet est monté sur /app :

docker run -d --name potato-study --restart unless-stopped \
  -p 127.0.0.1:8000:7860 \
  -v /srv/potato/my-study:/app \
  -e POTATO_SECRET_KEY="$(openssl rand -hex 32)" \
  ghcr.io/davidjurgens/potato:2.14.0

La commande publie l'étude uniquement sur le port 8000 de l'interface de bouclage de l'hôte. Le proxy inverse est alors l'unique point d'entrée. Le tag latest suit la branche de développement de Potato, et une étude doit épingler un tag de version. Générez POTATO_SECRET_KEY une fois et conservez la valeur, car une nouvelle clé à chaque démarrage déconnecte tous les annotateurs à chaque redémarrage. Le conteneur refuse de démarrer quand /app n'est pas accessible en écriture pour l'uid 1000. Exécutez le conteneur avec --user "$(id -u):$(id -g)" ou donnez le dossier à l'uid 1000. Exécuter Potato dans Docker couvre les tags et les variables d'environnement de l'image.

Sans Docker, Potato s'installe depuis PyPI avec Python 3.9 ou une version plus récente grâce à pip install potato-annotation. Ajoutez l'extra hosting pour les sauvegardes et l'authentification unique, et l'extra saml pour la connexion SAML, qui se compile contre la libxmlsec1 du système. potato start config.yaml exécute un serveur de développement qui ferme la connexion après chaque réponse. Pour des annotateurs qui travaillent par Internet, exécutez Potato sous gunicorn comme le montre Mise en production, ou placez un proxy inverse devant potato start.

Processus et nombre de workers

Potato garde le pool d'items, la file d'attribution et l'état de chaque annotateur dans la mémoire d'un seul processus. Un second worker gunicorn ou une seconde réplique détient une copie séparée de ces trois éléments, distribue des items que le premier processus a déjà attribués et écrase les sauvegardes du premier processus. L'image refuse donc de démarrer avec GUNICORN_WORKERS supérieur à 1. Pour plus de concurrence, augmentez GUNICORN_THREADS à partir de la valeur par défaut de 8. La documentation Docker de Potato estime que huit threads suffisent pour les dizaines d'annotateurs simultanés d'une étude typique. Exécutez plusieurs études comme plusieurs conteneurs, chacun avec un dossier et un port séparés.

Taille du serveur

La mémoire croît avec le nombre d'items. Les mesures de Potato situent chaque item entre 0,9 et 1,4 Ko en mémoire, et le serveur sur le jeu de données de référence de Potato a utilisé environ 365 Mo. potato deploy, la commande cloud de Potato, choisit une machine de 1 ou 2 vCPU et de 2 Go de mémoire chez la plupart des hébergeurs, ce qui est une taille de départ raisonnable.

Le disque doit être persistant et accessible en écriture, et il lui faut de la place pour les fichiers de données, pour les fichiers multimédias que contiennent les items et pour les annotations. Un conteneur dont le disque est effacé à chaque redémarrage perd toutes les annotations, sauf si la sauvegarde intégrée décrite plus bas est activée.

Accès réseau et HTTPS

Exposez Potato derrière un proxy inverse comme nginx, Apache ou Caddy. Le proxy détient le certificat TLS et transmet les requêtes au port du conteneur. Seuls les ports 443, et 80 pour les redirections et le renouvellement du certificat, doivent être ouverts sur Internet. Proxy inverse montre comment servir Potato sous un chemin d'URL comme https://host.example.edu/my-study/, avec POTATO_PROXY_FIX=1 et un en-tête X-Forwarded-Prefix ou avec POTATO_URL_PREFIX. Les visualiseurs d'agents en direct diffusent par événements envoyés par le serveur. Désactivez la mise en tampon du proxy sur l'emplacement /api/ si l'étude utilise ces visualiseurs.

GET /health ne demande aucune authentification et renvoie {"status": "ok"} une fois le serveur prêt, et 503 tant que le serveur charge encore les données. Pointez un répartiteur de charge ou une vérification de supervision vers cette route.

Potato n'a besoin d'aucun accès réseau sortant par défaut. Les scripts, les feuilles de style et les polices que les navigateurs des annotateurs chargent viennent du serveur lui-même, et Déploiement isolé du réseau et hors ligne liste la façon dont Potato garde l'installation par défaut hors ligne. L'accès sortant n'est nécessaire que pour les fonctionnalités que la configuration active :

• Les fonctionnalités d'IA appellent le point d'accès de modèle que nomme la configuration, sauf s'il s'agit d'un serveur de modèles local comme Ollama.
• Les sauvegardes écrivent dans le dataset Hugging Face ou le bucket S3 que nomme la configuration.
• L'authentification unique contacte le fournisseur d'identité.
• Les sources de données distantes lisent depuis le bucket ou la base de données que nomme la configuration.
• Les items qui pointent vers des médias par URL font récupérer ces médias par le navigateur de l'annotateur depuis cette URL.

Fichiers que Potato écrit

Potato écrit tout dans le dossier de l'étude :

Un seul répertoire contient donc toute l'étude. output_annotation_dir est un réglage de config.yaml, et le Study Designer lui donne la valeur output.

Sauvegardes

Une sauvegarde nocturne du dossier du projet couvre les fichiers d'annotations et la liste des comptes. Copiez les deux fichiers SQLite avec la commande de sauvegarde propre à SQLite plutôt que comme des fichiers, car la copie d'une base en mode WAL peut être corrompue ou manquer des écritures récentes :

sqlite3 /srv/potato/my-study/project.sqlite ".backup /backups/my-study/project.sqlite"

La sauvegarde intégrée de Potato copie la sortie des annotations et des instantanés des bases vers un bucket compatible S3 ou un dataset Hugging Face privé toutes les cinq minutes. Au démarrage, la sauvegarde restaure depuis le bucket quand le disque est vide, et elle n'écrase jamais des annotations déjà présentes sur le disque. Le bloc ci-dessous envoie la copie vers un stockage d'objets universitaire. Ajoutez le bloc au config.yaml de l'étude et définissez POTATO_S3_ACCESS_KEY_ID et POTATO_S3_SECRET_ACCESS_KEY dans l'environnement du conteneur :

backup:
  schedule_minutes: 5
  restore_on_boot: true
  sinks:
    - type: s3
      bucket: research-backups
      prefix: potato/my-study
      endpoint_url: https://s3.example.edu

L'image publiée inclut les clients de sauvegarde. Une installation avec pip a besoin de l'extra hosting.

Options de connexion

Potato prend en charge plusieurs façons de connecter les annotateurs, définies dans config.yaml :

Les mots de passe sont hachés avec PBKDF2-SHA256 à 100 000 itérations et un sel par utilisateur. Un mot de passe oublié se réinitialise par un lien à usage unique que Potato affiche à l'écran, et Potato n'envoie aucun courriel. Derrière un proxy qui termine TLS, définissez sp_base_url pour SAML sur l'adresse publique, faute de quoi la réponse du fournisseur d'identité échoue à la vérification de destination de Potato. SSO et OAuth, Gestion des mots de passe et Intégration du crowdsourcing donnent la configuration de chaque méthode.

Accès administrateur

Le tableau de bord d'administration à /admin montre l'avancement, l'accord et les réponses de chaque annotateur, et télécharge les résultats. Le tableau de bord s'ouvre avec une clé d'administration. Définissez la clé avec POTATO_ADMIN_API_KEY, ou laissez Potato générer admin_api_key.txt dans le dossier du projet à la première utilisation, et transmettez la clé au chercheur par un canal auquel votre établissement fait confiance. Gardez debug: false dans config.yaml sur tout serveur, car le mode debug ouvre les pages d'administration sans clé aux requêtes qui paraissent locales, et un proxy sur la même machine peut faire paraître locale chaque requête.

Protection des données

Potato est auto-hébergé, si bien que les annotations, la liste des comptes et les items restent sur le serveur que vous exploitez. Potato ne contient ni analytique ni rapport d'utilisation, et une installation par défaut n'établit aucune connexion sortante. Les données ne quittent le serveur que par les fonctionnalités listées sous Accès réseau et HTTPS, que la configuration de l'étude doit chacune activer et pour lesquelles elle doit nommer une destination.

Vérifiez trois points par rapport à l'approbation éthique de l'étude :

• Les fichiers d'annotations nomment chaque annotateur par son nom d'utilisateur, et des noms d'utilisateur qui sont des adresses électroniques mettent donc des adresses électroniques dans les données.
• Les pages d'enquête d'une étude peuvent recueillir des informations personnelles, et les réponses se trouvent dans les mêmes fichiers par annotateur.
• Quand la configuration envoie des items à un fournisseur de modèles hébergé, les items quittent le serveur selon les conditions de ce fournisseur.

Quand l'étude se termine, l'équipe de recherche télécharge les résultats depuis le tableau de bord d'administration. Convenez avec l'équipe de la durée de conservation de la copie du serveur, et supprimez le dossier du projet et tout bucket de sauvegarde après cette date.

Pour aller plus loin

• Exécuter Potato dans Docker, pour les tags de l'image, les variables d'environnement et la propriété des fichiers
• Mise en production, pour gunicorn, nginx, Apache et Docker Compose
• Proxy inverse, pour servir Potato sous un chemin d'URL
• Déploiement isolé du réseau et hors ligne, pour les réseaux sans accès sortant
• Mettre votre étude Potato en ligne, le côté chercheur du même processus