Server-Anforderungen von Potato für Ihre IT

Potato ist eine selbst gehostete Webanwendung für Annotationsstudien. Ein Potato-Prozess bedient eine Studie, hält jede Annotation in Dateien und SQLite-Datenbanken im Ordner der Studie und braucht für HTTPS einen Reverse Proxy vor dem Prozess. Eine Standardinstallation sendet nichts an externe Dienste, und Daten verlassen den Server nur über Funktionen, die die Konfiguration der Studie einschaltet.

Diese Seite richtet sich an die Personen, die an einer Universität, in einem Krankenhaus oder in einem Unternehmen Server betreiben. Forschende, die eine Studie hosten lassen möchten, können die Seite unverändert weiterleiten, zusammen mit dem Projektordner und den Antworten, die der nächste Abschnitt auflistet. Ihre Potato-Studie online stellen behandelt die Wege, die Forschende ohne IT gehen können.

Informationen vom Forschungsteam

Das Forschungsteam schickt den Projektordner, den der Study Designer als Download project (.zip) exportiert. Der Ordner enthält config.yaml, die Konfiguration der Studie, und die Datendateien, die die Konfiguration nennt. Zusammen mit dem Ordner beantwortet das Forschungsteam diese Fragen:

• Wie viele Annotatoren nehmen teil, und melden sich die Annotatoren mit Konten der Einrichtung an oder mit Benutzernamen, die die Forschenden auflisten?
• Wann beginnt und endet die Studie?
• Enthalten die Items oder die Antworten personenbezogene oder sensible Informationen, und unter welchem Ethikvotum läuft die Studie?
• Nutzt die Konfiguration KI-Funktionen, die Items an einen Modellanbieter senden? Blöcke wie ai_support, chat_support und solo_mode in config.yaml kennzeichnen solche Funktionen.

Software

Potato ist eine auf Flask aufbauende Python-Webanwendung. Die einfachste Installation ist das veröffentlichte Docker-Image ghcr.io/davidjurgens/potato, gebaut für linux/amd64 und linux/arm64. Das Image ist etwa 900 MB groß, führt Python 3.11 unter gunicorn als unprivilegierten Benutzer potato (uid 1000) aus und lauscht auf Port 7860. Der Projektordner wird unter /app eingebunden:

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

Der Befehl veröffentlicht die Studie nur auf Port 8000 der Loopback-Schnittstelle des Hosts. Der Reverse Proxy ist dann der einzige Zugang. Der Tag latest folgt dem Entwicklungszweig von Potato, und eine Studie sollte sich auf einen Versions-Tag festlegen. Erzeugen Sie POTATO_SECRET_KEY einmal und behalten Sie den Wert, denn ein neuer Schlüssel bei jedem Start meldet bei jedem Neustart alle Annotatoren ab. Der Container weigert sich zu starten, wenn /app nicht von uid 1000 beschreibbar ist. Führen Sie den Container mit --user "$(id -u):$(id -g)" aus oder übergeben Sie den Ordner an uid 1000. Potato in Docker ausführen behandelt die Tags und Umgebungsvariablen des Images.

Ohne Docker wird Potato auf Python 3.9 oder neuer mit pip install potato-annotation aus PyPI installiert. Fügen Sie das Extra hosting für Backups und Single Sign-on hinzu und das Extra saml für die SAML-Anmeldung, das gegen die libxmlsec1 des Systems gebaut wird. potato start config.yaml führt einen Entwicklungsserver aus, der die Verbindung nach jeder Antwort schließt. Für Annotatoren, die über das Internet arbeiten, führen Sie Potato unter gunicorn aus, wie es Produktionseinrichtung zeigt, oder stellen Sie einen Reverse Proxy vor potato start.

Prozess und Worker-Anzahl

Potato hält den Item-Pool, die Zuweisungswarteschlange und den Zustand jedes Annotators im Speicher eines Prozesses. Ein zweiter gunicorn-Worker oder ein zweites Replikat hält eine getrennte Kopie von allen dreien, vergibt Items, die der erste Prozess bereits zugewiesen hat, und überschreibt die Speicherstände des ersten Prozesses. Das Image weigert sich deshalb zu starten, wenn GUNICORN_WORKERS über 1 liegt. Für mehr Nebenläufigkeit erhöhen Sie GUNICORN_THREADS vom Standardwert 8. Die eigene Docker-Dokumentation von Potato setzt acht Threads für die Dutzende gleichzeitiger Annotatoren an, die eine typische Studie hat. Führen Sie mehrere Studien als mehrere Container aus, jeden Container mit eigenem Ordner und eigenem Port.

Servergröße

Der Speicherbedarf wächst mit der Zahl der Items. Die Messungen von Potato setzen jedes Item bei 0,9 bis 1,4 KB im Speicher an, und der Server benötigte beim Referenzdatensatz von Potato etwa 365 MB. potato deploy, der Cloud-Befehl von Potato, wählt auf den meisten Hosts eine Maschine mit 1 oder 2 vCPUs und 2 GB Speicher, was eine vernünftige Ausgangsgröße ist.

Der Datenträger muss persistent und beschreibbar sein und braucht Platz für die Datendateien, alle Mediendateien der Items und die Annotationen. Ein Container, dessen Datenträger beim Neustart gelöscht wird, verliert jede Annotation, sofern nicht das unten beschriebene eingebaute Backup eingeschaltet ist.

Netzwerkzugriff und HTTPS

Stellen Sie Potato über einen Reverse Proxy wie nginx, Apache oder Caddy bereit. Der Proxy hält das TLS-Zertifikat und leitet Anfragen an den Port des Containers weiter. Nur die Ports 443 sowie 80 für Weiterleitungen und die Zertifikatserneuerung müssen zum Internet hin offen sein. Reverse-Proxy (URL-Pfadpräfix) zeigt, wie Potato unter einem URL-Pfad wie https://host.example.edu/my-study/ bereitgestellt wird, über POTATO_PROXY_FIX=1 mit einem Header X-Forwarded-Prefix oder über POTATO_URL_PREFIX. Die Live-Agent-Viewer streamen mit Server-Sent Events. Schalten Sie das Proxy-Buffering für den Pfad /api/ aus, wenn die Studie diese Viewer nutzt.

GET /health braucht keine Authentifizierung und liefert {"status": "ok"}, sobald der Server bereit ist, und 503, solange der Server noch Daten lädt. Richten Sie einen Load Balancer oder eine Überwachungsprüfung auf diese Route.

Potato braucht standardmäßig keinen ausgehenden Netzwerkzugriff. Die Skripte, Stylesheets und Schriften, die die Browser der Annotatoren laden, kommen vom Server selbst, und Air-gapped- und Offline-Deployment listet auf, wie Potato die Standardinstallation offline hält. Ausgehender Zugriff ist nur für Funktionen nötig, die die Konfiguration einschaltet:

• KI-Funktionen rufen den Modell-Endpunkt auf, den die Konfiguration nennt, es sei denn, der Endpunkt ist ein lokaler Modellserver wie Ollama.
• Backups schreiben in das Hugging-Face-Dataset oder den S3-Bucket, den die Konfiguration nennt.
• Single Sign-on kontaktiert den Identitätsanbieter.
• Entfernte Datenquellen lesen aus dem Bucket oder der Datenbank, die die Konfiguration nennt.
• Items, die per URL auf Medien verweisen, lassen den Browser des Annotators die Medien von dieser URL abrufen.

Dateien, die Potato schreibt

Potato schreibt alles in den Ordner der Studie:

Ein Verzeichnis enthält somit die ganze Studie. output_annotation_dir ist eine Einstellung in config.yaml, und der Study Designer setzt den Wert auf output.

Backups

Ein nächtliches Backup des Projektordners deckt die Annotationsdateien und die Kontenliste ab. Kopieren Sie die beiden SQLite-Dateien mit dem eigenen Backup-Befehl von SQLite statt als Dateien, denn eine Dateikopie einer Datenbank im WAL-Modus kann beschädigt sein oder neuere Schreibvorgänge auslassen:

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

Das eingebaute Backup von Potato kopiert die Annotationsausgabe und Snapshots der Datenbanken alle fünf Minuten in einen S3-kompatiblen Bucket oder ein privates Hugging-Face-Dataset. Beim Start stellt das Backup aus dem Bucket wieder her, wenn der Datenträger leer ist, und überschreibt nie Annotationen, die bereits auf dem Datenträger liegen. Der folgende Block schickt die Kopie an einen Objektspeicher der Universität. Fügen Sie den Block der config.yaml der Studie hinzu und setzen Sie POTATO_S3_ACCESS_KEY_ID und POTATO_S3_SECRET_ACCESS_KEY in der Umgebung des Containers:

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

Das veröffentlichte Image enthält die Backup-Clients. Eine Installation mit pip braucht das Extra hosting.

Anmeldeoptionen

Potato unterstützt mehrere Wege, wie sich Annotatoren anmelden, festgelegt in config.yaml:

Passwörter werden mit PBKDF2-SHA256 bei 100.000 Iterationen und einem Salt pro Benutzer gehasht. Ein vergessenes Passwort wird über einen Einmal-Link zurückgesetzt, den Potato auf dem Bildschirm anzeigt, und Potato versendet keine E-Mails. Setzen Sie hinter einem Proxy, der TLS beendet, sp_base_url für SAML auf die öffentliche Adresse, sonst scheitert die Antwort des Identitätsanbieters an der Zielprüfung von Potato. SSO- und OAuth-Authentifizierung, Passwortverwaltung und Crowdsourcing-Integration geben die Konfiguration für jede Methode an.

Admin-Zugriff

Das Admin-Dashboard unter /admin zeigt Fortschritt, Übereinstimmung und die Antworten jedes Annotators und lädt die Ergebnisse herunter. Das Dashboard öffnet sich mit einem Admin-Schlüssel. Setzen Sie den Schlüssel über POTATO_ADMIN_API_KEY oder lassen Sie Potato bei der ersten Nutzung admin_api_key.txt im Projektordner erzeugen, und geben Sie den Schlüssel über einen Kanal, dem Ihre Einrichtung vertraut, an die Forschenden weiter. Lassen Sie debug: false in config.yaml auf jedem Server, denn der Debug-Modus öffnet die Admin-Seiten ohne Schlüssel für Anfragen, die lokal aussehen, und ein Proxy auf demselben Rechner kann jede Anfrage lokal aussehen lassen.

Datenschutz

Potato wird selbst gehostet, daher bleiben die Annotationen, die Kontenliste und die Items auf dem Server, den Sie betreiben. Potato enthält keine Analyse- oder Nutzungsberichte, und eine Standardinstallation baut keine ausgehenden Verbindungen auf. Daten verlassen den Server nur über die Funktionen, die unter Netzwerkzugriff und HTTPS aufgeführt sind, und jede davon muss die Konfiguration der Studie einschalten und mit einem Ziel versehen.

Prüfen Sie drei Punkte gegen das Ethikvotum der Studie:

• Die Annotationsdateien nennen jeden Annotator mit dem Benutzernamen, daher legen Benutzernamen, die E-Mail-Adressen sind, E-Mail-Adressen in die Daten.
• Umfrageseiten in einer Studie können personenbezogene Informationen erheben, und die Antworten liegen in denselben Dateien pro Annotator.
• Sendet die Konfiguration Items an einen gehosteten Modellanbieter, verlassen die Items den Server zu den Bedingungen dieses Anbieters.

Wenn die Studie endet, lädt das Forschungsteam die Ergebnisse aus dem Admin-Dashboard herunter. Vereinbaren Sie mit dem Team, wie lange die Kopie auf dem Server aufbewahrt wird, und löschen Sie nach diesem Datum den Projektordner und jeden Backup-Bucket.

Weiterführende Literatur

• Potato in Docker ausführen, für Tags, Umgebungsvariablen und Dateibesitz des Images
• Produktionseinrichtung, für gunicorn, nginx, Apache und Docker Compose
• Reverse-Proxy (URL-Pfadpräfix), um Potato unter einem URL-Pfad bereitzustellen
• Air-gapped- und Offline-Deployment, für Netzwerke ohne ausgehenden Zugriff
• Ihre Potato-Studie online stellen, die Seite der Forschenden zum selben Vorgang