Botones de despliegue: deja que otro laboratorio ejecute tu estudio de anotación

Este tutorial añade un botón de despliegue con un clic al repositorio git de un estudio de anotación, para que un colaborador, un estudiante u otro laboratorio pueda ejecutar el estudio en su propia cuenta en la nube sin instalar Potato. Un paquete de replicación suele incluir una configuración y un archivo de datos con instrucciones para instalar una herramienta y arrancar un servidor, y cada paso de esas instrucciones es un punto en el que una replicación puede atascarse. Un botón de despliegue las sustituye por un inicio de sesión en una cuenta y un clic, y cada despliegue hace una copia de seguridad de sus anotaciones en el almacenamiento que nombra quien despliega. Este tutorial describe Potato 2.12.0, la primera versión en la que cada persona que despliega nombra su propia copia de seguridad, así que genera los botones con 2.12.0 o posterior. También necesitas un estudio cuyos config.yaml y datos estén ya en un repositorio git.

Archivos que escribe un botón de despliegue

Heroku, Render y AWS CloudFormation pueden construir un servicio a partir de archivos de un repositorio. Heroku lee app.json, Render lee render.yaml y CloudFormation lee una plantilla. potato deploy button escribe esos archivos para tu estudio y muestra la insignia que hay que pegar en tu README. Tu propio config.yaml nunca se modifica. El comando escribe una copia a su lado, potato.deploy.yaml, con el modo de depuración desactivado, las sesiones persistentes y la copia de seguridad configurada, y los archivos generados apuntan a esa copia.

No entra ningún secreto en el repositorio. Heroku y Render generan la clave de sesión y la clave de administración cuando alguien despliega, la plantilla de AWS las genera en la instancia, y la persona que despliega aporta las credenciales de la copia de seguridad en el momento del despliegue.

Elegir un destino

Los cuatro destinos difieren en lo que necesita la persona que hace clic:

En Heroku, el botón ejecuta un dyno Basic por 7 $ al mes, y el disco del dyno se borra cada día. El botón de AWS crea una instancia de Lightsail por 12 $ al mes con un disco persistente, adecuada para un estudio que vaya a durar semanas. Railway publica las plantillas desde su propio panel, así que para ese destino el comando muestra los pasos en lugar de escribir archivos. Una plantilla de Railway copia tu propio despliegue, incluido el almacenamiento de la copia de seguridad, así que todas las personas que la desplegaran compartirían tu dataset, y los pasos que se muestran avisan de ello.

Añadir un botón de Heroku

Ejecuta el comando desde la raíz del repositorio, nombrando la configuración del estudio y el tipo de copia de seguridad:

potato deploy button studies/pilot/config.yaml --target heroku --backup hf

Los botones de Heroku y Render despliegan en discos que no sobreviven a un reinicio, y nadie recoge las anotaciones de la instancia de un botón de AWS, así que los tres destinos que escriben archivos exigen --backup. Cada cinco minutos, la copia de seguridad copia la salida de anotación e instantáneas de las bases de datos del proyecto al almacenamiento de la copia de seguridad, y un servidor reiniciado se restaura desde ella. La persona que despliega nombra ese almacenamiento al hacer clic en el botón: POTATO_BACKUP_HF_REPO y HF_TOKEN para un dataset de HuggingFace, o POTATO_BACKUP_S3_BUCKET con las claves del bucket para S3. Heroku y Render los piden sin valor por defecto, y la plantilla de AWS los recibe como parámetros obligatorios de la pila, así que cada despliegue hace la copia de seguridad en su propio almacenamiento. button ignora --hf-backup-repo, --hf-token, --s3-bucket, --s3-region y --s3-endpoint, y lo indica.

Un botón generado con Potato 2.11.1 o anterior escribía tu dataset en potato.deploy.yaml con la restauración al arrancar activada. Quien desplegaba sin permiso de escritura sobre él tenía copias de seguridad fallidas, quien sí tenía permiso de escritura enviaba sus anotaciones a tu dataset, y un despliegue nuevo podía restaurar a tus anotadores. Vuelve a generar un botón así con 2.12.0 y --force, y después haz commit de los archivos y push.

Antes de escribir nada, el comando comprueba dos archivos. Heroku y Render construyen una imagen a partir de tu repositorio, y .potato/ (la clave de administración y los secretos del despliegue), annotation_output/ y las bases de datos SQLite tienen que quedar fuera de ella. Si el repositorio no tiene .dockerignore, el comando escribe uno, y si existe uno sin esas entradas, las enumera. También enumera cualquiera de esas rutas que git check-ignore no informe como ignorada, ya que un botón despliega lo que hayas subido.

Haz commit de los archivos generados y push:

git add app.json heroku.yml Dockerfile.potato .dockerignore studies/pilot/potato.deploy.yaml
git commit -m "Add a Deploy to Heroku button"
git push

Pega en tu README la insignia que mostró el comando. Un visitante que hace clic en ella inicia sesión en Heroku, nombra su propio dataset para la copia de seguridad e introduce un token para él, y obtiene el estudio en marcha en una dirección que asigna Heroku.

Añadir un botón AWS Launch Stack

CloudFormation solo lee plantillas desde S3, así que el botón de AWS requiere un paso más. Genera la plantilla, súbela a un bucket tuyo y vuelve a generar el botón con la URL de la plantilla:

potato deploy button config.yaml --target aws --backup hf
aws s3 cp potato-lightsail.cfn.yaml s3://my-bucket/ --acl public-read
potato deploy button config.yaml --target aws --backup hf \
    --template-url https://my-bucket.s3.amazonaws.com/potato-lightsail.cfn.yaml --force

La pila crea una instancia de Lightsail y una IP estática. La instancia clona tu repositorio público, genera sus secretos y arranca Potato con un certificado para la IP estática. La salida URL de la pila es la dirección que hay que dar a los anotadores, lista unos minutos después de que se complete la pila. La clave de administración se queda en la instancia, y la persona que desplegó la lee desde el SSH en el navegador de Lightsail con sudo grep ADMIN /opt/potato/potato.env.

Fijar la versión de Potato y los datos

Una replicación debería ejecutar la misma versión de Potato que el original. Desde 2.11, el botón fija la imagen a la versión de Potato que lo generó. Potato 2.10 escribe en su lugar la etiqueta latest, así que un despliegue meses después ejecuta la versión de Potato que esté vigente entonces, y una corrección en la concordancia o en la exportación hecha entretanto puede cambiar los números que informa la replicación. En 2.10, fija la imagen con --image al generar el botón, por ejemplo --image ghcr.io/davidjurgens/potato:2.10.3. Fija los datos del mismo modo, haciendo commit de ellos junto con la configuración en lugar de descargarlos al arrancar.

--dry-run muestra todos los archivos sin escribir nada, así que puedes comprobar lo que haría un botón antes de hacer commit. Los archivos existentes solo se sustituyen con --force. Ejecutar Potato en local o en la nube presenta el botón junto con los demás destinos de despliegue, y la documentación de los botones de despliegue enumera todas las opciones.