Scripts de inicio

onstart es un script de bash que se ejecuta una sola vez, la primera vez que arranca una instancia. Es donde instala paquetes, descarga pesos, clona un repositorio o precalienta una caché — la preparación que de otro modo repetiría a mano después de cada despliegue.

Péguelo en Script de inicio en el formulario de la plantilla, o defina onstart a través de la API.

Dónde se ejecuta y dónde no

Modo de lanzamiento	Comportamiento
ssh	En una imagen base de Superheat, se ejecuta una vez después de que sshd y Jupyter hayan arrancado. En una imagen de terceros, solo se exporta
jupyter	Igual que ssh
vm	cloud-init lo escribe dentro del invitado y lo ejecuta una vez en el primer arranque
args	Se exporta, no se ejecuta por nosotros: se entrega como SUPERHEAT_ONSTART y solo corre si la imagen lo lee

En modo args, el entrypoint propio de la imagen es el dueño del proceso, y eso es deliberado: sustituirlo por el entrypoint de Superheat descartaría su comando, que es todo el contenido de una plantilla args. Así que el script se entrega al contenedor como SUPERHEAT_ONSTART y no se hace nada más con él.

Lo que decide si se ejecuta es la imagen, no el modo. Una imagen base de Superheat lee SUPERHEAT_ONSTART desde su propio entrypoint, ejecuta el script una vez y luego hace exec de su comando, así que una plantilla args sobre una de las nuestras sí lo ejecuta. Una imagen de terceros nunca ha oído hablar de la variable y la ignora, tanto en modo ssh como en args. Si su script no se está ejecutando, mueva la plantilla a una imagen base de Superheat, incluya la preparación en su propia imagen, o haga que sea lo primero que hace su comando.

Llega como una variable de entorno

El cuerpo del script se entrega al contenedor como la variable de entorno SUPERHEAT_ONSTART. Nunca se monta como un archivo desde el host. El entrypoint de la imagen base lee esa variable, escribe el cuerpo en /var/lib/superheat/onstart.sh con el modo 0700 y lo ejecuta. El nombre simple ONSTART se acepta como alias, por compatibilidad con imágenes que ya lo leen.

De ahí se derivan cuatro consecuencias, y las cuatro afectan a quien da por hecho que hay un archivo montado.

El cuerpo se entrega literalmente, así que usted no escapa nada por Superheat. Las comillas, las barras invertidas, los saltos de línea, los heredocs y los $ llegan al contenedor exactamente como los escribió. Escriba el script como lo escribiría en un editor, no como lo escribiría dentro de un argumento bash -c "…". La expansión de variables ocurre dentro del contenedor, cuando bash ejecuta el archivo, contra el entorno del contenedor — no antes.

El script se ejecuta con bash, así que un shebang es decorativo. Poner #!/usr/bin/env python3 arriba no lo convierte en un script de Python; lo convierte en un script de bash cuya primera línea es un comentario, y cuya línea siguiente es un error de sintaxis. Para ejecutar algo que no sea bash, haga que el script escriba el contenido a un archivo e invoque el intérprete correcto.

La longitud está acotada. El campo de la plantilla limita onstart a 65,536 caracteres, que no es lugar para un contenido grande. Si su preparación ocupa más de una o dos pantallas, póngala en un repositorio y haga que el script de inicio la descargue y la ejecute — eso además le da control de versiones sobre la parte que más cambia.

No se puede leer desde su shell. El entrypoint excluye deliberadamente SUPERHEAT_ONSTART del entorno que exporta a los shells de login, junto con el token de Jupyter y las variables de la clave SSH. Imprimir $SUPERHEAT_ONSTART por SSH no devuelve nada. Lea /var/lib/superheat/onstart.sh en su lugar si necesita ver qué se ejecutó.

Ejecutarse una vez significa una vez

Con éxito o con fallo, el entrypoint escribe un centinela en /var/lib/superheat/.onstart-done y nunca vuelve a ejecutar el script en ese contenedor. Detener e iniciar una instancia vuelve a ejecutar el entrypoint, pero el centinela hace que se salte el cuerpo del script de inicio, así que una preparación aplicada a medias no se reintenta en silencio encima de sí misma.

Si su script falla, el contenedor sigue en pie. El fallo se registra, no es fatal, precisamente para que pueda entrar por SSH y arreglarlo a mano. Importan dos destinos de log:

cat /var/log/superheat/onstart.log     # your script's own output

La línea de resumen del entrypoint, incluido el código de salida, también llega a los logs de la instancia en la consola. Consulte Leer los logs.

Como sshd arranca antes que el script de inicio, puede conectarse mientras todavía se está ejecutando y observarlo:

tail -f /var/log/superheat/onstart.log

Para volver a ejecutarlo después de un arreglo, borre el centinela y ejecute el script usted mismo:

rm -f /var/lib/superheat/.onstart-done
bash /var/lib/superheat/onstart.sh

Un ejemplo resuelto

Este instala dependencias, descarga un modelo con el token suministrado como variable de entorno secreta y deja una marca para que sepa de un vistazo si terminó.

set -euo pipefail

echo "onstart: $(date -u +%FT%TZ) on ${GPU_COUNT} GPU(s)"

pip install --no-cache-dir -r /workspace/requirements.txt

# HF_TOKEN comes from a template env entry marked secret, or from
# env_overrides at deploy time. Never hard-code it here.
if [ -n "${HF_TOKEN:-}" ]; then
  huggingface-cli download meta-llama/Llama-3-8B \
    --local-dir /workspace/models/llama-3-8b
else
  echo "HF_TOKEN unset — skipping model download" >&2
fi

date -u +%FT%TZ > /workspace/.setup-complete
echo "onstart: done"

Puntos que vale la pena copiar: set -euo pipefail para que un paso fallido detenga el script en lugar de dejar un entorno a medio construir, ${HF_TOKEN:-} para que una variable no definida no aborte bajo set -u, y escribir todo dentro de /workspace para que sobreviva a una detención y un inicio.

Nunca ponga una credencial en el script de inicio

El script de inicio de una plantilla pública puede leerlo cualquier usuario de Superheat, y una receta compartida lo lleva literalmente. Ponga los tokens en entradas de entorno marcadas como secretas y léalos desde el script, como arriba. Consulte Variables de entorno.

Editarlo después

onstart forma parte de la receta de lanzamiento, así que cambiarlo vuelve a generar el hash_id de la plantilla. Las instancias que ya están en ejecución conservan el script con el que se lanzaron — una edición solo llega a las instancias desplegadas después.