Deploy-Buttons: Ein anderes Labor Ihre Annotationsstudie ausführen lassen

Dieses Tutorial fügt dem Git-Repository einer Annotationsstudie einen Deploy-Button für die Bereitstellung mit einem Klick hinzu, sodass eine Kooperationspartnerin, ein Student oder ein anderes Labor die Studie im eigenen Cloud-Konto ausführen kann, ohne Potato zu installieren. Ein Replikationspaket enthält meist eine Konfiguration und eine Datendatei mit der Anleitung, ein Werkzeug zu installieren und einen Server zu starten, und jeder Schritt dieser Anleitung ist eine Stelle, an der eine Replikation ins Stocken geraten kann. Ein Deploy-Button ersetzt sie durch eine Anmeldung im Konto und einen Klick, und jedes Deployment sichert seine Annotationen in einem Speicher, den die bereitstellende Person angibt. Dieses Tutorial beschreibt Potato 2.12.0, die erste Version, in der jede bereitstellende Person ihr eigenes Backup angibt; erzeugen Sie Buttons daher mit 2.12.0 oder neuer. Außerdem brauchen Sie eine Studie, deren config.yaml und Daten bereits in einem Git-Repository liegen.

Dateien, die ein Deploy-Button schreibt

Heroku, Render und AWS CloudFormation können jeweils einen Dienst aus Dateien in einem Repository bauen. Heroku liest app.json, Render liest render.yaml, und CloudFormation liest ein Template. potato deploy button schreibt diese Dateien für Ihre Studie und gibt das Badge aus, das Sie in Ihre README einfügen. Ihre eigene config.yaml wird nie verändert. Der Befehl schreibt daneben eine Kopie, potato.deploy.yaml, mit ausgeschaltetem Debug-Modus, persistenten Sitzungen und konfiguriertem Backup, und die erzeugten Dateien verweisen auf diese Kopie.

Es kommen keine Geheimnisse ins Repository. Heroku und Render erzeugen den Sitzungsschlüssel und den Admin-Schlüssel, wenn jemand bereitstellt, das AWS-Template erzeugt sie auf der Instanz, und die bereitstellende Person gibt die Zugangsdaten für das Backup beim Deployment an.

Ein Ziel wählen

Die vier Ziele unterscheiden sich darin, was die klickende Person braucht:

Auf Heroku betreibt der Button einen Basic-Dyno für 7 $ im Monat, und die Festplatte des Dynos wird täglich gelöscht. Der AWS-Button erstellt eine Lightsail-Instanz für 12 $ im Monat mit einer Festplatte, die erhalten bleibt, was zu einer Studie passt, die über Wochen läuft. Railway veröffentlicht Templates aus seinem eigenen Dashboard, daher gibt der Befehl für dieses Ziel die Schritte aus, statt Dateien zu schreiben. Ein Railway-Template kopiert Ihr eigenes Deployment einschließlich des Backup-Speichers, sodass alle, die es bereitstellen, Ihr Dataset teilen würden, und die ausgegebenen Schritte warnen davor.

Einen Heroku-Button hinzufügen

Führen Sie den Befehl im Wurzelverzeichnis des Repositorys aus und nennen Sie die Konfiguration der Studie und die Art des Backups:

potato deploy button studies/pilot/config.yaml --target heroku --backup hf

Die Heroku- und Render-Buttons stellen auf Festplatten bereit, die einen Neustart nicht überstehen, und von der Instanz eines AWS-Buttons holt niemand die Annotationen ab, daher verlangen alle drei Ziele, die Dateien schreiben, --backup. Alle fünf Minuten kopiert das Backup die Annotationsausgabe und Snapshots der Projektdatenbanken in den Backup-Speicher, und ein neu gestarteter Server stellt daraus wieder her. Die bereitstellende Person nennt diesen Speicher, wenn sie auf den Button klickt: POTATO_BACKUP_HF_REPO und HF_TOKEN für ein HuggingFace-Dataset oder POTATO_BACKUP_S3_BUCKET mit den Schlüsseln des Buckets für S3. Heroku und Render fragen diese Werte ohne Vorgabe ab, und das AWS-Template nimmt sie als erforderliche Stack-Parameter, sodass jedes Deployment in seinen eigenen Speicher sichert. button ignoriert --hf-backup-repo, --hf-token, --s3-bucket, --s3-region und --s3-endpoint und weist darauf hin.

Ein mit Potato 2.11.1 oder früher erzeugter Button schrieb Ihr Dataset in potato.deploy.yaml, mit eingeschalteter Wiederherstellung beim Start. Eine bereitstellende Person ohne Schreibzugriff darauf bekam fehlschlagende Backups, eine mit Schreibzugriff schickte ihre Annotationen in Ihr Dataset, und ein neues Deployment konnte Ihre Annotatoren wiederherstellen. Erzeugen Sie einen solchen Button mit 2.12.0 und --force neu, committen Sie dann die Dateien und pushen Sie.

Bevor er etwas schreibt, prüft der Befehl zwei Dateien. Heroku und Render bauen ein Image aus Ihrem Repository, und .potato/ (der Admin-Schlüssel und die Deploy-Geheimnisse), annotation_output/ und die SQLite-Datenbanken müssen draußen bleiben. Hat das Repository keine .dockerignore, schreibt der Befehl eine, und gibt es eine ohne diese Einträge, listet er sie auf. Außerdem listet er jeden dieser Pfade auf, den git check-ignore nicht als ignoriert meldet, da ein Button alles bereitstellt, was Sie gepusht haben.

Committen Sie die erzeugten Dateien und pushen Sie:

git add app.json heroku.yml Dockerfile.potato .dockerignore studies/pilot/potato.deploy.yaml
git commit -m "Add a Deploy to Heroku button"
git push

Fügen Sie das Badge, das der Befehl ausgegeben hat, in Ihre README ein. Wer darauf klickt, meldet sich bei Heroku an, nennt ein eigenes Backup-Dataset, gibt ein Token dafür ein und erhält die laufende Studie unter einer Adresse, die Heroku vergibt.

Einen AWS-Launch-Stack-Button hinzufügen

CloudFormation liest Templates nur aus S3, daher braucht der AWS-Button einen Schritt mehr. Erzeugen Sie das Template, laden Sie es in einen Bucket hoch, der Ihnen gehört, und erzeugen Sie den Button dann erneut mit der URL des Templates:

potato deploy button config.yaml --target aws --backup hf
aws s3 cp potato-lightsail.cfn.yaml s3://my-bucket/ --acl public-read
potato deploy button config.yaml --target aws --backup hf \
    --template-url https://my-bucket.s3.amazonaws.com/potato-lightsail.cfn.yaml --force

Der Stack erstellt eine Lightsail-Instanz und eine statische IP. Die Instanz klont Ihr öffentliches Repository, erzeugt ihre Geheimnisse und startet Potato mit einem Zertifikat für die statische IP. Die Stack-Ausgabe URL ist die Adresse, die Sie an Annotatoren weitergeben, bereit einige Minuten nach Abschluss des Stacks. Der Admin-Schlüssel bleibt auf der Instanz, und die Person, die bereitgestellt hat, liest ihn über die Browser-SSH von Lightsail mit sudo grep ADMIN /opt/potato/potato.env aus.

Die Potato-Version und die Daten festschreiben

Eine Replikation sollte dieselbe Potato-Version ausführen wie das Original. Ab 2.11 pinnt der Button das Image auf die Potato-Version, die ihn erzeugt hat. Potato 2.10 schreibt stattdessen das Tag latest, sodass ein Deployment Monate später die dann aktuelle Potato-Version ausführt, und eine zwischenzeitliche Korrektur an Übereinstimmung oder Export kann die Zahlen ändern, die die Replikation berichtet. Pinnen Sie unter 2.10 das Image beim Erzeugen des Buttons mit --image, zum Beispiel --image ghcr.io/davidjurgens/potato:2.10.3. Schreiben Sie die Daten auf dieselbe Weise fest, indem Sie sie mit der Konfiguration committen, statt sie beim Start herunterzuladen.

--dry-run gibt alle Dateien aus, ohne etwas zu schreiben, sodass Sie prüfen können, was ein Button tun würde, bevor Sie ihn committen. Bestehende Dateien werden nur mit --force ersetzt. Potato lokal oder in der Cloud ausführen behandelt den Button neben den anderen Deployment-Zielen, und die Dokumentation zu Deploy-Buttons listet alle Optionen auf.