Requisitos de servidor de Potato para tu equipo de TI

Potato es una aplicación web autoalojada para estudios de anotación. Un proceso de Potato sirve un estudio, guarda todas las anotaciones en archivos y bases de datos SQLite dentro de la carpeta del estudio y necesita un proxy inverso delante del proceso para HTTPS. Una instalación por defecto no envía nada a servicios externos, y los datos salen del servidor solo a través de las funciones que activa la configuración del estudio.

Esta página está escrita para las personas que gestionan servidores en una universidad, un hospital o una empresa. Un investigador que quiera que se aloje un estudio puede enviar la página sin cambios, junto con la carpeta del proyecto y las respuestas que se enumeran en la sección siguiente. Pon tu estudio de Potato en línea cubre las vías que un investigador puede seguir sin un equipo de TI.

Información del equipo de investigación

El equipo de investigación envía la carpeta del proyecto, que el Study Designer exporta como Download project (.zip). La carpeta contiene config.yaml, la configuración del estudio, y los archivos de datos que nombra la configuración. Junto con la carpeta, el equipo de investigación responde a estas preguntas:

• ¿Cuántos anotadores participan, y los anotadores inician sesión con cuentas institucionales o con nombres de usuario que lista el investigador?
• ¿Cuándo empieza y cuándo termina el estudio?
• ¿Los ítems o las respuestas contienen información personal o sensible, y bajo qué aprobación ética se realiza el estudio?
• ¿La configuración usa funciones de IA que envían ítems a un proveedor de modelos? Bloques como ai_support, chat_support y solo_mode en config.yaml señalan esas funciones.

Software

Potato es una aplicación web de Python construida sobre Flask. La instalación más sencilla es la imagen de Docker publicada, ghcr.io/davidjurgens/potato, compilada para linux/amd64 y linux/arm64. La imagen ocupa unos 900 MB, ejecuta Python 3.11 bajo gunicorn como el usuario sin privilegios potato (uid 1000) y escucha en el puerto 7860. La carpeta del proyecto se monta en /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

El comando publica el estudio solo en el puerto 8000 de la interfaz de loopback del host. El proxy inverso es entonces la única entrada. La etiqueta latest sigue la rama de desarrollo de Potato, y un estudio debe fijar una etiqueta de versión. Genera POTATO_SECRET_KEY una sola vez y conserva el valor, porque una clave nueva en cada arranque cierra la sesión de todos los anotadores en cada reinicio. El contenedor se niega a arrancar cuando el uid 1000 no puede escribir en /app. Ejecuta el contenedor con --user "$(id -u):$(id -g)" o cede la carpeta al uid 1000. Ejecutar Potato en Docker cubre las etiquetas de la imagen y las variables de entorno.

Sin Docker, Potato se instala desde PyPI en Python 3.9 o posterior con pip install potato-annotation. Añade el extra hosting para las copias de seguridad y el inicio de sesión único, y el extra saml para el inicio de sesión con SAML, que se compila contra libxmlsec1 del sistema. potato start config.yaml ejecuta un servidor de desarrollo que cierra la conexión tras cada respuesta. Para anotadores que trabajan por internet, ejecuta Potato bajo gunicorn como muestra Configuración de producción, o pon un proxy inverso delante de potato start.

Proceso y número de workers

Potato guarda el conjunto de ítems, la cola de asignación y el estado de cada anotador en la memoria de un solo proceso. Un segundo worker de gunicorn o una segunda réplica tiene una copia separada de las tres cosas, reparte ítems que el primer proceso ya asignó y sobrescribe los guardados del primer proceso. Por eso la imagen se niega a arrancar con GUNICORN_WORKERS por encima de 1. Para más concurrencia, aumenta GUNICORN_THREADS desde el valor por defecto de 8. La propia documentación de Docker de Potato sitúa ocho hilos en las decenas de anotadores simultáneos que tiene un estudio típico. Ejecuta varios estudios como varios contenedores, cada uno con una carpeta y un puerto distintos.

Tamaño del servidor

La memoria crece con el número de ítems. Las mediciones de Potato sitúan cada ítem entre 0,9 y 1,4 KB en memoria, y el servidor con el conjunto de datos de referencia de Potato usó unos 365 MB. potato deploy, el comando de nube propio de Potato, elige una máquina con 1 o 2 vCPU y 2 GB de memoria en la mayoría de los hosts, que es un tamaño inicial razonable.

El disco tiene que ser persistente y admitir escritura, y necesita espacio para los archivos de datos, los archivos multimedia que incluyan los ítems y las anotaciones. Un contenedor cuyo disco se borra al reiniciar pierde todas las anotaciones, salvo que esté activada la copia de seguridad integrada que se describe más abajo.

Acceso a la red y HTTPS

Expón Potato a través de un proxy inverso como nginx, Apache o Caddy. El proxy guarda el certificado TLS y reenvía las solicitudes al puerto del contenedor. Solo hace falta abrir a internet los puertos 443 y, para las redirecciones y la renovación de certificados, el 80. Proxy inverso muestra cómo servir Potato bajo una ruta de URL como https://host.example.edu/my-study/, con POTATO_PROXY_FIX=1 y un encabezado X-Forwarded-Prefix o con POTATO_URL_PREFIX. Los visores de agentes en vivo transmiten con server-sent events. Desactiva el almacenamiento en búfer del proxy en la ubicación /api/ si el estudio usa esos visores.

GET /health no necesita autenticación y devuelve {"status": "ok"} cuando el servidor está listo, y 503 mientras el servidor aún carga datos. Apunta un balanceador de carga o una comprobación de monitorización a esa ruta.

Potato no necesita acceso de red saliente por defecto. Los scripts, las hojas de estilo y las fuentes que cargan los navegadores de los anotadores proceden del propio servidor, y Despliegue aislado de la red y sin conexión enumera cómo mantiene Potato sin conexión la instalación por defecto. El acceso saliente solo hace falta para las funciones que activa la configuración:

• Las funciones de IA llaman al endpoint de modelo que nombra la configuración, salvo que el endpoint sea un servidor de modelos local como Ollama.
• Las copias de seguridad escriben en el conjunto de datos de Hugging Face o el bucket de S3 que nombra la configuración.
• El inicio de sesión único contacta con el proveedor de identidad.
• Las fuentes de datos remotas leen del bucket o de la base de datos que nombra la configuración.
• Los ítems que enlazan a archivos multimedia por URL hacen que el navegador del anotador obtenga el archivo desde esa URL.

Archivos que escribe Potato

Potato escribe todo en la carpeta del estudio:

Un único directorio contiene por tanto todo el estudio. output_annotation_dir es un ajuste de config.yaml, y el Study Designer define el valor como output.

Copias de seguridad

Una copia de seguridad nocturna de la carpeta del proyecto cubre los archivos de anotaciones y la lista de cuentas. Copia los dos archivos SQLite con el comando de copia de seguridad propio de SQLite en lugar de como archivos, porque una copia de archivo de una base de datos en modo WAL puede estar corrupta o carecer de las escrituras recientes:

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

La copia de seguridad integrada de Potato copia la salida de anotaciones y las instantáneas de las bases de datos a un bucket compatible con S3 o a un conjunto de datos privado de Hugging Face cada cinco minutos. Al arrancar, la copia de seguridad restaura desde el bucket cuando el disco está vacío, y nunca sobrescribe las anotaciones que ya están en el disco. El bloque siguiente envía la copia a un almacén de objetos universitario. Añade el bloque al config.yaml del estudio y define POTATO_S3_ACCESS_KEY_ID y POTATO_S3_SECRET_ACCESS_KEY en el entorno del contenedor:

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

La imagen publicada incluye los clientes de copia de seguridad. Una instalación con pip necesita el extra hosting.

Opciones de inicio de sesión

Potato admite varias formas de que los anotadores inicien sesión, definidas en config.yaml:

Las contraseñas se procesan con hash PBKDF2-SHA256 con 100 000 iteraciones y una sal por usuario. Una contraseña olvidada se restablece mediante un enlace de un solo uso que Potato muestra en pantalla, y Potato no envía ningún correo. Detrás de un proxy que termina TLS, define sp_base_url para SAML con la dirección pública, o la respuesta del proveedor de identidad falla en la comprobación de destino de Potato. Autenticación SSO y OAuth, Gestión de contraseñas e Integración de crowdsourcing dan la configuración de cada método.

Acceso de administración

El panel de administración en /admin muestra el progreso, el acuerdo y las respuestas de todos los anotadores, y descarga los resultados. El panel se abre con una clave de administración. Define la clave con POTATO_ADMIN_API_KEY, o deja que Potato genere admin_api_key.txt en la carpeta del proyecto en el primer uso, y entrega la clave al investigador por un canal en el que confíe tu institución. Mantén debug: false en config.yaml en cualquier servidor, porque el modo de depuración abre las páginas de administración sin clave a las solicitudes que parecen locales, y un proxy en la misma máquina puede hacer que todas las solicitudes parezcan locales.

Protección de datos

Potato es autoalojado, así que las anotaciones, la lista de cuentas y los ítems permanecen en el servidor que ejecutas. Potato no contiene ninguna analítica ni informe de uso, y una instalación por defecto no realiza conexiones salientes. Los datos salen del servidor solo a través de las funciones enumeradas en Acceso a la red y HTTPS, y la configuración del estudio tiene que activar cada una y nombrar un destino para ella.

Comprueba tres puntos con la aprobación ética del estudio:

• Los archivos de anotaciones nombran a cada anotador por su nombre de usuario, así que los nombres de usuario que son direcciones de correo ponen direcciones de correo en los datos.
• Las páginas de encuesta de un estudio pueden recoger información personal, y las respuestas están en los mismos archivos por anotador.
• Cuando la configuración envía ítems a un proveedor de modelos alojado, los ítems salen del servidor bajo los términos de ese proveedor.

Cuando termina el estudio, el equipo de investigación descarga los resultados desde el panel de administración. Acuerda con el equipo cuánto tiempo se conserva la copia del servidor, y elimina la carpeta del proyecto y cualquier bucket de copias de seguridad después de esa fecha.

Más información

• Ejecutar Potato en Docker, para las etiquetas de la imagen, las variables de entorno y la propiedad de archivos
• Configuración de producción, para gunicorn, nginx, Apache y Docker Compose
• Proxy inverso, para servir Potato bajo una ruta de URL
• Despliegue aislado de la red y sin conexión, para redes sin acceso saliente
• Pon tu estudio de Potato en línea, el lado del investigador del mismo proceso