Exécuter Potato en local ou dans le cloud

Potato s'exécute sur votre propre machine avec deux commandes, et potato deploy place la même configuration sur un hébergeur cloud avec une commande de plus. Cette page associe chaque situation courante à un hébergeur et donne la commande correspondante. Les cibles cloud ci-dessous exigent Potato 2.10.0 ou une version ultérieure. Cette version a ajouté AWS, Heroku, Fly, Railway, Hetzner, Vultr, Linode et OpenStack aux cibles DigitalOcean, Render et HuggingFace que la 2.9 proposait déjà.

Choisir où exécuter une tâche

Le bon hébergeur dépend du temps pendant lequel la tâche doit rester en ligne et de qui la paie. Les coûts du tableau sont les estimations que Potato 2.10.0 affiche pour la taille par défaut de chaque cible, et --dry-run affiche l'estimation pour la taille que vous choisissez.

Sur AWS, utilisez Lightsail, que crée --provider aws. Son prix forfaitaire inclut l'adresse IPv4 et un disque de 60 Go, et il ne demande que les permissions lightsail:*, si bien qu'il fonctionne sous un rôle IAM restreint. La cible EC2 (aws-ec2) est destinée aux comptes où Lightsail est désactivé.

Jetstream2 est un cloud de recherche financé par la NSF. Avec une allocation ACCESS, il ne coûte rien, et chaque instance reçoit un nom DNS, si bien que les annotateurs voient un nom d'hôte ordinaire avec un certificat ordinaire. L'instance par défaut consomme 2 unités de service par heure, soit environ 17 500 sur un an, donc détruisez-la quand l'étude se termine.

Exécuter Potato sur votre propre machine

Potato nécessite Python 3.9 ou une version plus récente. Installez-le et lancez une tâche :

pip install potato-annotation
potato start myproject/config.yaml -p 8000

La tâche est accessible à http://localhost:8000, et personne d'autre ne peut l'atteindre. potato start lit la configuration et les fichiers de données là où ils se trouvent, si bien qu'un redémarrage prend en compte une modification. C'est donc la commande à utiliser pendant que vous écrivez une tâche. Le Démarrage rapide construit une première configuration, et Installation couvre les extras optionnels et les environnements virtuels.

L'image Docker publiée ne nécessite pas Python sur l'hôte. Elle contient Potato et ses dépendances, et votre dossier de projet, avec config.yaml et ses données, est monté sur /app :

docker run -p 8000:7860 -v "$PWD/myproject:/app" ghcr.io/davidjurgens/potato:latest

Le conteneur écoute sur le port 7860, que la commande associe au port 8000 de votre machine. Mise en production couvre les tags de l'image, ses variables d'environnement et l'erreur de propriété des fichiers que signalent les hôtes Linux.

Un lien public temporaire avec potato share

potato share exécute la tâche et la rend accessible par un lien HTTPS public tant que la commande tourne. Il lui faut un client de tunnel, et il utilise cloudflared, Tailscale ou ngrok, dans cet ordre, selon celui qui est installé :

brew install cloudflared
potato share myproject/config.yaml

Le lien cesse de fonctionner quand vous appuyez sur Ctrl-C, quand l'ordinateur portable se met en veille ou quand le réseau change, et les annotations restent sur votre propre disque. Avant d'ouvrir le tunnel, potato share affiche qui pourra se connecter et vous demande de confirmer, car les règles de connexion de la configuration s'appliquent alors à quiconque possède le lien. Certains réseaux universitaires bloquent les liens trycloudflare.com, et --backend tailscale contourne ce blocage. Utilisez potato share pour un pilote ou une réunion de laboratoire, et un hébergeur cloud pour toute tâche à laquelle un participant pourrait revenir le lendemain.

Déployer dans le cloud en une commande

potato deploy up prend la configuration que vous avez déjà, crée le serveur, obtient un certificat HTTPS, téléverse le projet, démarre la tâche et affiche l'URL. Installez l'extra correspondant à votre cible, puis examinez le plan avant de l'exécuter :

pip install 'potato-annotation[deploy]'            # most targets
pip install 'potato-annotation[deploy-aws]'        # the three AWS targets
pip install 'potato-annotation[deploy-openstack]'  # Jetstream2 and other OpenStack clouds
 
potato deploy up myproject/config.yaml --provider aws --dry-run
potato deploy up myproject/config.yaml --provider aws

--dry-run ne nécessite aucun compte. Il affiche chaque ressource que le déploiement créerait, le coût mensuel et tout réglage de votre configuration qui présente un risque sur un serveur public. Sans --dry-run, Potato affiche le même plan et attend votre confirmation avant de créer quoi que ce soit. Relancer up sur la même configuration met à jour le déploiement existant, et après le premier up, status, logs, pull et destroy n'ont plus besoin de --provider.

Les treize cibles cloud

Potato 2.10.0 déploie vers treize cibles cloud. Elles diffèrent surtout par la survie ou non du disque à un redémarrage, ce qui détermine si un déploiement a besoin de la sauvegarde décrite dans la section suivante.

Les sept cibles VM (aws, aws-ec2, openstack, hetzner, vultr, linode et digitalocean) sont configurées de la même façon. Chacune reçoit une clé de déploiement générée pour ce déploiement, un pare-feu qui n'ouvre que les ports 22, 80 et 443, Caddy avec un certificat Let's Encrypt, et Potato en tant que service systemd, et potato deploy logs et pull fonctionnent sur toutes. Fly, Railway, Render et ECS Express exécutent l'image publiée et téléchargent votre projet au démarrage du conteneur. Railway, Render et ECS Express le récupèrent depuis le stockage de sauvegarde, donc tous trois nécessitent --backup, et un service Railway ou Render doté d'un disque en a besoin lui aussi. Sur Fly, un projet de moins de 512 Ko voyage dans la configuration de la Machine et ne nécessite aucun stockage.

Google Cloud Run, Azure Container Apps et AWS App Runner ne sont pas des cibles. Le stockage que proposent Cloud Run et Azure Container Apps ne peut pas héberger une base de données SQLite de façon sûre, et App Runner n'accepte plus de nouveaux clients depuis le 30 avril 2026. Sur Azure, une VM qui exécute l'image Docker fonctionne.

Sauvegardes pour les hébergeurs qui effacent leur disque

Sur Heroku, ECS Express, l'offre gratuite de Render et HuggingFace Spaces, le disque est effacé au redémarrage du serveur. --backup copie toutes les cinq minutes la sortie des annotations et des instantanés des bases de données du projet vers un dataset HuggingFace ou un bucket S3, et les restaure quand un serveur démarre avec un disque vide :

potato deploy up myproject/config.yaml --provider heroku --backup hf --hf-token hf_...
potato deploy up myproject/config.yaml --provider heroku --backup s3 --s3-bucket my-bucket

Heroku et ECS Express refusent de déployer sans --backup, sauf si --demo déclare les annotations jetables. La restauration ramène la liste des comptes en même temps que les annotations, si bien que les annotateurs se connectent avec les mêmes mots de passe et reprennent là où ils s'étaient arrêtés, et elle n'écrase jamais des annotations déjà présentes sur le disque. --s3-endpoint envoie la sauvegarde S3 vers Cloudflare R2, Backblaze B2, MinIO ou un stockage objet universitaire. La sauvegarde fonctionne aussi sur les cibles VM, où elle conserve une seconde copie des données hors du serveur.

En dehors de potato deploy, un bloc backup dans la configuration remplit la même fonction sur un serveur que vous exploitez vous-même. Installez l'extra hosting, qui fournit les clients HuggingFace et S3, définissez HF_TOKEN dans l'environnement du serveur, et ajoutez ce bloc à une configuration existante :

backup:
  schedule_minutes: 5
  restore_on_boot: true
  sinks:
    - type: huggingface
      repo_id: lab/pilot-annotations

Récupérer les annotations avant destroy

potato deploy pull télécharge tout ce qu'un déploiement a collecté dans un répertoire horodaté et vérifie ce qui est arrivé, et potato deploy destroy supprime le serveur. Exécutez-les dans cet ordre :

potato deploy pull myproject/config.yaml
potato deploy destroy myproject/config.yaml

destroy refuse de supprimer un déploiement qui n'a jamais fait l'objet d'un pull, et un pull qui ne renvoie aucun fichier ne compte pas. Le pull copie project.sqlite au moyen de la commande de sauvegarde de SQLite plutôt que comme un simple fichier, car la copie de fichier d'une base de données en mode WAL peut ne pas contenir le travail récent. Sur Fly et Railway, détruire l'application supprime son volume, si bien que le pull est la seule copie, sauf si vous avez aussi lancé une sauvegarde.

Boutons de déploiement pour les comptes d'autres personnes

potato deploy button écrit les fichiers qu'une plateforme d'hébergement lit pour proposer un déploiement en un clic depuis votre dépôt git, et affiche le badge pour le README. Utilisez-le quand des collaborateurs, des étudiants ou un autre laboratoire doivent exécuter votre tâche dans leurs propres comptes :

potato deploy button studies/pilot/config.yaml --target heroku \
    --backup hf --hf-backup-repo lab/pilot-annotations

Les cibles sont heroku, render, aws et railway. La cible aws écrit un modèle CloudFormation « Launch Stack » qui crée une instance Lightsail, et pour railway la commande affiche les étapes à suivre, car Railway publie les modèles depuis son tableau de bord. Votre config.yaml reste inchangé, et la commande écrit à côté une copie, potato.deploy.yaml, à laquelle les réglages de déploiement sont appliqués. Aucun secret n'entre dans le dépôt. Heroku, Render et le modèle AWS génèrent les clés de session et d'administration au moment du déploiement. Les boutons Heroku, Render et AWS exigent --backup, et la personne qui déploie fournit les identifiants de la sauvegarde.

Pour aller plus loin

Chaque cible a sa propre page dans la documentation de Potato :

• Installer et exécuter Potato et Déployer une tâche, le cycle de vie complet de potato deploy
• AWS : Lightsail, EC2 et ECS Express, avec les permissions IAM que chacun exige
• Jetstream2 et OpenStack, y compris la marche à suivre pour demander une allocation
• Hetzner, Vultr et Linode et DigitalOcean
• Fly.io, Railway, Render, Heroku et HuggingFace Spaces
• Sauvegardes, Récupérer les annotations et Boutons de déploiement
• Partager une tâche sur une URL temporaire

Sur ce site, Mise en production couvre l'exécution de Potato sous gunicorn et Docker sur un serveur que vous gérez, et Proxy inverse sa mise à disposition sous un préfixe de chemin d'URL.