Requisiti del server Potato per il tuo team IT

Potato è un'applicazione web self-hosted per studi di annotazione. Un processo Potato serve uno studio, conserva ogni annotazione in file e database SQLite dentro la cartella dello studio e ha bisogno di un reverse proxy davanti al processo per HTTPS. Un'installazione predefinita non invia nulla a servizi esterni, e i dati lasciano il server solo attraverso le funzioni che la configurazione dello studio attiva.

Questa pagina è scritta per chi gestisce i server in un'università, in un ospedale o in un'azienda. Un ricercatore che vuole far ospitare uno studio può inviare la pagina così com'è, insieme alla cartella del progetto e alle risposte elencate nella sezione successiva. Mettere online il tuo studio Potato tratta i percorsi che un ricercatore può seguire senza un team IT.

Informazioni dal gruppo di ricerca

Il gruppo di ricerca invia la cartella del progetto, che lo Study Designer esporta con Download project (.zip). La cartella contiene config.yaml, la configurazione dello studio, e i file di dati che la configurazione nomina. Insieme alla cartella, il gruppo di ricerca risponde a queste domande:

• Quanti annotatori partecipano, e gli annotatori accedono con account istituzionali o con nomi utente che il ricercatore elenca?
• Quando iniziano e finiscono le attività dello studio?
• Gli item o le risposte contengono informazioni personali o sensibili, e con quale approvazione etica si svolge lo studio?
• La configurazione usa funzioni di intelligenza artificiale che inviano item a un fornitore di modelli? Blocchi come ai_support, chat_support e solo_mode in config.yaml indicano queste funzioni.

Software

Potato è un'applicazione web Python costruita su Flask. L'installazione più semplice è l'immagine Docker pubblicata, ghcr.io/davidjurgens/potato, costruita per linux/amd64 e linux/arm64. L'immagine pesa circa 900 MB, esegue Python 3.11 sotto gunicorn come utente senza privilegi potato (uid 1000) e resta in ascolto sulla porta 7860. La cartella del progetto viene montata su /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

Il comando pubblica lo studio soltanto sulla porta 8000 dell'interfaccia di loopback dell'host. Il reverse proxy è quindi l'unico ingresso. Il tag latest segue il branch di sviluppo di Potato, e uno studio dovrebbe fissare un tag di versione. Genera POTATO_SECRET_KEY una sola volta e conserva il valore, perché una nuova chiave a ogni avvio disconnette tutti gli annotatori a ogni riavvio. Il container rifiuta di avviarsi quando /app non è scrivibile dall'uid 1000. Esegui il container con --user "$(id -u):$(id -g)" oppure assegna la cartella all'uid 1000. Eseguire Potato in Docker tratta i tag dell'immagine e le variabili d'ambiente.

Senza Docker, Potato si installa da PyPI su Python 3.9 o successivo con pip install potato-annotation. Aggiungi l'extra hosting per i backup e il single sign-on, e l'extra saml per l'accesso SAML, che viene compilato contro la libxmlsec1 del sistema. potato start config.yaml esegue un server di sviluppo che chiude la connessione dopo ogni risposta. Per annotatori che lavorano via internet, esegui Potato sotto gunicorn come mostra Configurazione di produzione, oppure metti un reverse proxy davanti a potato start.

Processo e numero di worker

Potato tiene il pool degli item, la coda di assegnazione e lo stato di ogni annotatore nella memoria di un solo processo. Un secondo worker gunicorn o una seconda replica tiene una copia separata di tutti e tre, distribuisce item che il primo processo aveva già assegnato e sovrascrive i salvataggi del primo processo. L'immagine rifiuta quindi di avviarsi con GUNICORN_WORKERS superiore a 1. Per più concorrenza, aumenta GUNICORN_THREADS rispetto al valore predefinito di 8. La documentazione Docker di Potato indica che otto thread bastano per le decine di annotatori simultanei di uno studio tipico. Esegui più studi come più container, ciascuno con una cartella e una porta separate.

Dimensione del server

La memoria cresce con il numero di item. Le misurazioni di Potato indicano da 0,9 a 1,4 KB di memoria per item, e il server sul dataset di riferimento di Potato ha usato circa 365 MB. potato deploy, il comando cloud di Potato, sceglie su quasi tutti gli host una macchina con 1 o 2 vCPU e 2 GB di memoria, che è una dimensione di partenza ragionevole.

Il disco deve essere persistente e scrivibile, e deve avere spazio per i file di dati, per gli eventuali file multimediali inclusi negli item e per le annotazioni. Un container il cui disco viene cancellato al riavvio perde ogni annotazione, a meno che il backup integrato descritto più sotto sia attivo.

Accesso di rete e HTTPS

Esponi Potato tramite un reverse proxy come nginx, Apache o Caddy. Il proxy detiene il certificato TLS e inoltra le richieste alla porta del container. Solo le porte 443, e 80 per i reindirizzamenti e il rinnovo del certificato, devono essere aperte verso internet. Proxy inverso (prefisso del percorso URL) mostra come servire Potato sotto un percorso URL come https://host.example.edu/my-study/, tramite POTATO_PROXY_FIX=1 con un header X-Forwarded-Prefix oppure tramite POTATO_URL_PREFIX. I visualizzatori degli agenti dal vivo trasmettono con server-sent events. Disattiva il buffering del proxy sulla location /api/ se lo studio usa quei visualizzatori.

GET /health non richiede autenticazione e restituisce {"status": "ok"} quando il server è pronto, e 503 mentre il server sta ancora caricando i dati. Punta un load balancer o un controllo di monitoraggio su quella route.

Per impostazione predefinita Potato non ha bisogno di alcun accesso di rete in uscita. Gli script, i fogli di stile e i font che i browser degli annotatori caricano provengono dal server stesso, e Deployment air-gapped e offline elenca come Potato mantiene offline l'installazione predefinita. L'accesso in uscita serve solo per le funzioni che la configurazione attiva:

• Le funzioni di intelligenza artificiale chiamano l'endpoint del modello che la configurazione nomina, a meno che l'endpoint sia un server di modelli locale come Ollama.
• I backup scrivono sul dataset Hugging Face o sul bucket S3 che la configurazione nomina.
• Il single sign-on contatta il provider di identità.
• Le origini dati remote leggono dal bucket o dal database che la configurazione nomina.
• Gli item che collegano file multimediali tramite URL fanno sì che il browser dell'annotatore scarichi il file da quell'URL.

File scritti da Potato

Potato scrive tutto nella cartella dello studio:

Una sola directory contiene quindi l'intero studio. output_annotation_dir è un'impostazione di config.yaml, e lo Study Designer imposta il valore su output.

Backup

Un backup notturno della cartella del progetto copre i file delle annotazioni e l'elenco degli account. Copia i due file SQLite con il comando di backup di SQLite invece che come file, perché la copia di un database in modalità WAL può risultare corrotta o priva delle scritture recenti:

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

Il backup integrato di Potato copia l'output delle annotazioni e gli snapshot dei database su un bucket compatibile con S3 o su un dataset Hugging Face privato ogni cinque minuti. All'avvio, il backup ripristina i dati dal bucket quando il disco è vuoto, e non sovrascrive mai le annotazioni già presenti sul disco. Il blocco qui sotto invia la copia a un object store universitario. Aggiungi il blocco al config.yaml dello studio e imposta POTATO_S3_ACCESS_KEY_ID e POTATO_S3_SECRET_ACCESS_KEY nell'ambiente del container:

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'immagine pubblicata include i client di backup. Un'installazione con pip richiede l'extra hosting.

Opzioni di accesso

Potato supporta diversi modi di accesso per gli annotatori, impostati in config.yaml:

Le password vengono sottoposte a hash con PBKDF2-SHA256 a 100.000 iterazioni e un salt per utente. Una password dimenticata si reimposta tramite un link monouso che Potato mostra a schermo, e Potato non invia alcuna email. Dietro un proxy che termina TLS, imposta sp_base_url per SAML sull'indirizzo pubblico, altrimenti la risposta del provider di identità non supera il controllo di destinazione di Potato. Autenticazione SSO e OAuth, Gestione delle password e Integrazione con il crowdsourcing forniscono la configurazione per ciascun metodo.

Accesso amministrativo

La dashboard di amministrazione su /admin mostra l'avanzamento, l'accordo e le risposte di ogni annotatore, e scarica i risultati. La dashboard si apre con una chiave di amministrazione. Imposta la chiave tramite POTATO_ADMIN_API_KEY, oppure lascia che Potato generi admin_api_key.txt nella cartella del progetto al primo utilizzo, e consegna la chiave al ricercatore attraverso un canale di cui la tua istituzione si fida. Mantieni debug: false in config.yaml su qualsiasi server, perché la modalità debug apre le pagine di amministrazione senza chiave alle richieste che sembrano locali, e un proxy sulla stessa macchina può far sembrare locale ogni richiesta.

Protezione dei dati

Potato è self-hosted, quindi le annotazioni, l'elenco degli account e gli item restano sul server che gestisci. Potato non contiene analytics né report di utilizzo, e un'installazione predefinita non effettua connessioni in uscita. I dati lasciano il server solo attraverso le funzioni elencate in Accesso di rete e HTTPS, ciascuna delle quali la configurazione dello studio deve attivare e per la quale deve nominare una destinazione.

Controlla tre punti rispetto all'approvazione etica dello studio:

• I file delle annotazioni identificano ogni annotatore con il nome utente, quindi nomi utente che sono indirizzi email mettono indirizzi email nei dati.
• Le pagine di sondaggio di uno studio possono raccogliere informazioni personali, e le risposte stanno negli stessi file per annotatore.
• Quando la configurazione invia item a un fornitore di modelli ospitato, gli item lasciano il server secondo i termini di quel fornitore.

Quando lo studio finisce, il gruppo di ricerca scarica i risultati dalla dashboard di amministrazione. Concorda con il gruppo per quanto tempo conservare la copia sul server, ed elimina la cartella del progetto e qualsiasi bucket di backup dopo quella data.

Ulteriori letture

• Eseguire Potato in Docker, per i tag dell'immagine, le variabili d'ambiente e la proprietà dei file
• Configurazione di produzione, per gunicorn, nginx, Apache e Docker Compose
• Proxy inverso (prefisso del percorso URL), per servire Potato sotto un percorso URL
• Deployment air-gapped e offline, per reti senza accesso in uscita
• Mettere online il tuo studio Potato, il lato del ricercatore dello stesso processo