Eseguire Potato in locale o nel cloud

Potato si esegue sulla tua macchina con due comandi, e potato deploy porta la stessa configurazione su un host cloud con un comando in più. Questa pagina associa a ogni situazione comune un host e indica il comando da usare. Le destinazioni cloud qui sotto richiedono Potato 2.10.0 o successivo, che ha aggiunto AWS, Heroku, Fly, Railway, Hetzner, Vultr, Linode e OpenStack alle destinazioni DigitalOcean, Render e HuggingFace già presenti nella 2.9.

Scegliere dove eseguire un task

L'host giusto dipende da quanto a lungo il task deve restare online e da chi lo paga. I costi in tabella sono le stime che Potato 2.10.0 stampa per la dimensione predefinita di ciascuna destinazione, e --dry-run stampa la stima per la dimensione che scegli.

Su AWS, usa Lightsail, che è ciò che crea --provider aws. Il suo prezzo fisso include l'indirizzo IPv4 e un disco da 60 GB, e richiede solo i permessi lightsail:*, quindi funziona anche con un ruolo IAM limitato. La destinazione EC2 (aws-ec2) serve per gli account in cui Lightsail è disattivato.

Jetstream2 è un cloud per la ricerca finanziato dalla NSF. Con un'allocazione ACCESS non costa nulla, e ogni istanza riceve un nome DNS, quindi gli annotatori vedono un normale nome host con un normale certificato. L'istanza predefinita consuma 2 unità di servizio all'ora, circa 17.500 in un anno, quindi distruggila quando lo studio finisce.

Eseguire Potato sulla tua macchina

Potato richiede Python 3.9 o successivo. Installalo e avvia un task:

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

Il task si trova su http://localhost:8000, e nessun altro può raggiungerlo. potato start legge la configurazione e i file di dati dove si trovano, quindi un riavvio recepisce una modifica, ed è per questo il comando da usare mentre scrivi un task. La Guida rapida costruisce una prima configurazione, e Installazione tratta gli extra opzionali e gli ambienti virtuali.

L'immagine Docker pubblicata non richiede Python sull'host. Contiene Potato e le sue dipendenze, e la cartella del progetto, con config.yaml e i suoi dati, viene montata su /app:

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

Il container serve sulla porta 7860, che il comando mappa sulla 8000 della tua macchina. Configurazione di produzione tratta i tag dell'immagine, le sue variabili d'ambiente e l'errore di proprietà dei file che segnalano gli host Linux.

Un link pubblico temporaneo con potato share

potato share esegue il task e lo rende raggiungibile tramite un link HTTPS pubblico finché il comando resta in esecuzione. Richiede un client di tunnel, e usa cloudflared, Tailscale o ngrok, in quest'ordine, a seconda di quale è installato:

brew install cloudflared
potato share myproject/config.yaml

Il link smette di funzionare quando premi Ctrl-C, quando il portatile va in sospensione o quando la rete cambia, e le annotazioni restano sul tuo disco. Prima di aprire il tunnel, potato share mostra chi potrà accedere e ti chiede di confermare, perché le regole di accesso della configurazione si applicano poi a chiunque abbia il link. Alcune reti universitarie bloccano i link trycloudflare.com, e --backend tailscale aggira il blocco. Usa potato share per un pilota o una riunione di laboratorio, e un host cloud per qualsiasi task a cui un partecipante potrebbe tornare il giorno dopo.

Distribuire nel cloud con un solo comando

potato deploy up prende la configurazione che hai già, crea il server, ottiene un certificato HTTPS, carica il progetto, avvia il task e stampa l'URL. Installa l'extra per la tua destinazione, poi esamina il piano prima di eseguirlo:

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 non richiede alcun account. Stampa ogni risorsa che il deployment creerebbe, il costo mensile e qualsiasi impostazione della tua configurazione che sia rischiosa su un server pubblico. Senza --dry-run, Potato mostra lo stesso piano e attende la tua conferma prima di creare qualsiasi cosa. Eseguire di nuovo up sulla stessa configurazione aggiorna il deployment esistente, e dopo il primo up, status, logs, pull e destroy non richiedono --provider.

Le tredici destinazioni cloud

Potato 2.10.0 distribuisce su tredici destinazioni cloud. Si differenziano soprattutto per il fatto che il disco sopravviva o meno a un riavvio, il che decide se un deployment ha bisogno del backup descritto nella sezione successiva.

Le sette destinazioni VM (aws, aws-ec2, openstack, hetzner, vultr, linode e digitalocean) vengono configurate allo stesso modo. Ciascuna riceve una chiave di deploy generata per quel deployment, un firewall che apre solo le porte 22, 80 e 443, Caddy con un certificato Let's Encrypt e Potato come servizio systemd, e potato deploy logs e pull funzionano su tutte. Fly, Railway, Render ed ECS Express eseguono l'immagine pubblicata e scaricano il progetto all'avvio del container. Railway, Render ed ECS Express lo prendono dallo storage di backup, quindi tutti e tre richiedono --backup, e lo richiede anche un servizio Railway o Render con un disco. Su Fly, un progetto sotto i 512 KB viaggia dentro la configurazione della Machine e non richiede storage.

Google Cloud Run, Azure Container Apps e AWS App Runner non sono destinazioni supportate. Lo storage offerto da Cloud Run e Azure Container Apps non può ospitare un database SQLite in modo sicuro, e App Runner non accetta nuovi clienti dal 30 aprile 2026. Su Azure funziona una VM che esegue l'immagine Docker.

Backup per gli host che cancellano il disco

Su Heroku, ECS Express, il piano gratuito di Render e HuggingFace Spaces, il disco viene cancellato al riavvio del server. --backup copia ogni cinque minuti l'output delle annotazioni e gli snapshot dei database del progetto su un dataset HuggingFace o un bucket S3, e li ripristina quando un server parte con il disco vuoto:

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 ed ECS Express si rifiutano di distribuire senza --backup, a meno che --demo non dichiari le annotazioni sacrificabili. Il ripristino riporta l'elenco degli account insieme alle annotazioni, quindi gli annotatori accedono con le stesse password e riprendono da dove si erano fermati, e non sovrascrive mai le annotazioni già presenti sul disco. --s3-endpoint invia il backup S3 a Cloudflare R2, Backblaze B2, MinIO o un object store universitario. Il backup funziona anche sulle destinazioni VM, dove conserva una seconda copia dei dati fuori dal server.

Al di fuori di potato deploy, un blocco backup nella configurazione fa lo stesso lavoro su un server che gestisci tu. Installa l'extra hosting, che fornisce i client HuggingFace e S3, imposta HF_TOKEN nell'ambiente del server e aggiungi questo blocco a una configurazione esistente:

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

Recuperare le annotazioni prima di destroy

potato deploy pull scarica tutto ciò che un deployment ha raccolto in una directory con data e ora e verifica ciò che è arrivato, e potato deploy destroy rimuove il server. Eseguili in quest'ordine:

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

destroy si rifiuta di rimuovere un deployment su cui non è mai stato eseguito un pull, e un pull che restituisce zero file non conta. Il pull copia project.sqlite tramite il comando di backup di SQLite anziché come file, perché la copia a livello di file di un database in modalità WAL può non contenere il lavoro recente. Su Fly e Railway, distruggere l'app elimina il suo volume, quindi il pull è l'unica copia, a meno che tu non abbia eseguito anche un backup.

Pulsanti di deploy per gli account di altre persone

potato deploy button scrive i file che una piattaforma di hosting legge per offrire un deploy con un clic dal tuo repository git, e stampa il badge per il README. Usalo quando collaboratori, studenti o un altro laboratorio devono eseguire il tuo task nei propri account:

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

Le destinazioni sono heroku, render, aws e railway. La destinazione aws scrive un template CloudFormation "Launch Stack" che crea un'istanza Lightsail, e per railway il comando stampa i passaggi da seguire, perché Railway pubblica i template dalla propria dashboard. Il tuo config.yaml resta invariato, e il comando scrive accanto una copia, potato.deploy.yaml, con le impostazioni di deployment applicate. Nessun segreto finisce nel repository. Heroku, Render e il template AWS generano le chiavi di sessione e di amministrazione al momento del deploy. I pulsanti Heroku, Render e AWS richiedono --backup, e le relative credenziali le fornisce chi esegue il deploy.

Approfondimenti

Ogni destinazione ha una propria pagina nella documentazione di Potato:

• Installare ed eseguire Potato e Distribuire un task, il ciclo di vita completo di potato deploy
• AWS: Lightsail, EC2 ed ECS Express, con i permessi IAM che ciascuno richiede
• Jetstream2 e OpenStack, compreso come richiedere un'allocazione
• Hetzner, Vultr e Linode e DigitalOcean
• Fly.io, Railway, Render, Heroku e HuggingFace Spaces
• Backup, Recuperare le annotazioni e Pulsanti di deploy
• Condividere un task su un URL temporaneo

Su questo sito, Configurazione di produzione spiega come eseguire Potato con gunicorn e Docker su un server che gestisci tu, e Proxy inverso come servirlo sotto un prefisso di percorso URL.