Ejecutar Potato en local o en la nube

Potato se ejecuta en tu propia máquina con dos comandos, y potato deploy lleva la misma configuración a un host en la nube con uno más. Esta página asigna un host a cada situación habitual y da el comando correspondiente. Los destinos en la nube que aparecen más abajo requieren Potato 2.10.0 o posterior, que añadió AWS, Heroku, Fly, Railway, Hetzner, Vultr, Linode y OpenStack a los destinos DigitalOcean, Render y HuggingFace que ya tenía 2.9.

Elegir dónde ejecutar una tarea

El host adecuado depende de cuánto tiempo tenga que estar disponible la tarea y de quién la pague. Los costes de la tabla son las estimaciones que Potato 2.10.0 muestra para el tamaño por defecto de cada destino, y --dry-run muestra la estimación para el tamaño que elijas.

En AWS, usa Lightsail, que es lo que crea --provider aws. Su precio fijo incluye la dirección IPv4 y un disco de 60 GB, y solo necesita permisos lightsail:*, así que funciona con un rol de IAM restringido. El destino EC2 (aws-ec2) es para cuentas en las que Lightsail está desactivado.

Jetstream2 es una nube de investigación financiada por la NSF. Con una asignación de ACCESS no cuesta nada, y cada instancia recibe un nombre DNS, de modo que los anotadores ven un nombre de host normal con un certificado normal. La instancia por defecto consume 2 unidades de servicio por hora, unas 17 500 al año, así que elimínala cuando termine el estudio.

Ejecutar Potato en tu propia máquina

Potato necesita Python 3.9 o posterior. Instálalo e inicia una tarea:

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

La tarea está en http://localhost:8000, y nadie más puede acceder a ella. potato start lee la configuración y los archivos de datos allí donde están, así que un reinicio recoge cualquier cambio, y por eso es el comando que conviene usar mientras escribes una tarea. El Inicio rápido crea una primera configuración, e Instalación explica los extras opcionales y los entornos virtuales.

La imagen de Docker publicada no necesita Python en el host. Contiene Potato y sus dependencias, y la carpeta de tu proyecto, con config.yaml y sus datos, se monta en /app:

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

El contenedor sirve en el puerto 7860, que el comando asigna al puerto 8000 de tu máquina. Configuración de producción explica las etiquetas de la imagen, sus variables de entorno y el error de propiedad de archivos que aparece en los hosts Linux.

Un enlace público temporal con potato share

potato share ejecuta la tarea y la publica en un enlace HTTPS público mientras el comando siga en marcha. Necesita un cliente de túnel, y usa cloudflared, Tailscale o ngrok, en ese orden, según cuál esté instalado:

brew install cloudflared
potato share myproject/config.yaml

El enlace deja de funcionar cuando pulsas Ctrl-C, cuando el portátil entra en reposo o cuando cambia la red, y las anotaciones se quedan en tu propio disco. Antes de abrir el túnel, potato share muestra quién podrá iniciar sesión y te pide confirmación, porque a partir de ese momento las reglas de inicio de sesión de la configuración se aplican a cualquiera que tenga el enlace. Algunas redes universitarias bloquean los enlaces de trycloudflare.com, y --backend tailscale evita el bloqueo. Usa potato share para un piloto o una reunión del laboratorio, y un host en la nube para cualquier tarea a la que un participante pueda volver al día siguiente.

Desplegar en la nube con un solo comando

potato deploy up toma la configuración que ya tienes, crea el servidor, obtiene un certificado HTTPS, sube el proyecto, inicia la tarea y muestra la URL. Instala el extra de tu destino y revisa el plan antes de ejecutarlo:

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 no necesita ninguna cuenta. Muestra cada recurso que crearía el despliegue, el coste mensual y cualquier ajuste de tu configuración que sea arriesgado en un servidor público. Sin --dry-run, Potato muestra el mismo plan y espera a que confirmes antes de crear nada. Volver a ejecutar up con la misma configuración actualiza el despliegue existente, y después del primer up, status, logs, pull y destroy no necesitan --provider.

Los trece destinos en la nube

Potato 2.10.0 despliega en trece destinos en la nube. Se diferencian sobre todo en si el disco sobrevive a un reinicio, y eso decide si un despliegue necesita el respaldo descrito en la sección siguiente.

Los siete destinos de VM (aws, aws-ec2, openstack, hetzner, vultr, linode y digitalocean) se configuran de la misma manera. Cada uno recibe una clave de despliegue generada para ese despliegue, un cortafuegos que solo abre los puertos 22, 80 y 443, Caddy con un certificado de Let's Encrypt y Potato como servicio de systemd, y potato deploy logs y pull funcionan en todos ellos. Fly, Railway, Render y ECS Express ejecutan la imagen publicada y descargan tu proyecto cuando arranca el contenedor. Railway, Render y ECS Express lo obtienen del almacenamiento del respaldo, así que los tres necesitan --backup, y un servicio de Railway o Render con disco también lo necesita. En Fly, un proyecto de menos de 512 KB viaja dentro de la configuración de la Machine y no necesita almacenamiento.

Google Cloud Run, Azure Container Apps y AWS App Runner no son destinos. El almacenamiento que ofrecen Cloud Run y Azure Container Apps no puede alojar una base de datos SQLite de forma segura, y App Runner dejó de aceptar clientes nuevos el 30 de abril de 2026. En Azure funciona una VM que ejecute la imagen de Docker.

Respaldos para hosts que borran su disco

En Heroku, ECS Express, el nivel gratuito de Render y HuggingFace Spaces, el disco se borra cuando el servidor se reinicia. --backup copia cada cinco minutos la salida de anotaciones e instantáneas de las bases de datos del proyecto a un dataset de HuggingFace o a un bucket de S3, y las restaura cuando un servidor arranca con el disco vacío:

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 y ECS Express se niegan a desplegar sin --backup, salvo que --demo declare desechables las anotaciones. La restauración recupera la lista de cuentas junto con las anotaciones, así que los anotadores inician sesión con las mismas contraseñas y continúan donde lo dejaron, y nunca sobrescribe anotaciones que ya estén en el disco. --s3-endpoint envía el respaldo de S3 a Cloudflare R2, Backblaze B2, MinIO o un almacenamiento de objetos de la universidad. El respaldo también funciona en los destinos de VM, donde mantiene una segunda copia de los datos fuera del servidor.

Fuera de potato deploy, un bloque backup en la configuración hace lo mismo en un servidor que gestionas tú. Instala el extra hosting, que proporciona los clientes de HuggingFace y S3, define HF_TOKEN en el entorno del servidor y añade este bloque a una configuración existente:

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

Descargar las anotaciones antes de destroy

potato deploy pull descarga todo lo que ha recogido un despliegue en un directorio con marca de tiempo y comprueba lo que ha llegado, y potato deploy destroy elimina el servidor. Ejecútalos en ese orden:

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

destroy se niega a eliminar un despliegue cuyos datos nunca se han descargado, y una descarga que devuelve cero archivos no cuenta. La descarga copia project.sqlite mediante el comando de copia de seguridad de SQLite y no como un archivo, porque la copia de archivo de una base de datos en modo WAL puede no incluir el trabajo reciente. En Fly y Railway, eliminar la app borra su volumen, así que lo descargado es la única copia, salvo que también hayas activado un respaldo.

Botones de despliegue para las cuentas de otras personas

potato deploy button escribe los archivos que lee una plataforma de hosting para ofrecer un despliegue con un clic desde tu repositorio git, y muestra la insignia para el README. Úsalo cuando colaboradores, estudiantes u otro laboratorio deban ejecutar tu tarea en sus propias cuentas:

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

Los destinos son heroku, render, aws y railway. El destino aws escribe una plantilla «Launch Stack» de CloudFormation que crea una instancia de Lightsail, y para railway el comando muestra los pasos, porque Railway publica las plantillas desde su panel. Tu config.yaml no se modifica, y el comando escribe a su lado una copia, potato.deploy.yaml, con los ajustes de despliegue aplicados. Ningún secreto entra en el repositorio. Heroku, Render y la plantilla de AWS generan las claves de sesión y de administración en el momento del despliegue. Los botones de Heroku, Render y AWS requieren --backup, y quien despliega aporta sus credenciales.

Lecturas adicionales

Cada destino tiene su propia página en la documentación de Potato:

• Instalar y ejecutar Potato y Desplegar una tarea, el ciclo de vida completo de potato deploy
• AWS: Lightsail, EC2 y ECS Express, con los permisos de IAM que necesita cada uno
• Jetstream2 y OpenStack, incluido cómo solicitar una asignación
• Hetzner, Vultr y Linode y DigitalOcean
• Fly.io, Railway, Render, Heroku y HuggingFace Spaces
• Respaldos, Recuperar las anotaciones y Botones de despliegue
• Compartir una tarea en una URL temporal

En este sitio, Configuración de producción explica cómo ejecutar Potato con gunicorn y Docker en un servidor que gestionas tú, y Proxy inverso explica cómo servirlo bajo un prefijo de ruta de URL.