Imagen base

Los modos de lanzamiento ssh y jupyter necesitan una imagen que incluya un servidor SSH, JupyterLab y el contrato de inicio. Una imagen upstream simple como pytorch/pytorch no incluye nada de eso, y por eso esos dos modos se restringen a imágenes derivadas de la base de Superheat.

superheat/base

Ese es el nombre canónico, en Docker Hub. La imagen también se replica en ghcr.io/superheat-software/base con un conjunto de etiquetas idéntico, publicado por la misma compilación — así que cualquiera de las dos referencias funciona, y los hosts recurren a la réplica si Docker Hub no está disponible. Prefiera el nombre corto.

Ambos son públicos, así que los hosts los descargan sin credenciales y usted no necesita credenciales de registro en una plantilla que use la base.

Etiquetas publicadas

Etiqueta	Qué es
cuda-12.1	CUDA 12.1
cuda-12.4	CUDA 12.4
cuda-12.6	CUDA 12.6
cuda-12.8	CUDA 12.8
latest	la versión menor de CUDA más reciente
sha-<12 chars>-<minor>	una etiqueta inmutable por cada compilación y versión menor de CUDA

Cada etiqueta cuda-<minor> se construye a partir de la imagen de runtime de CUDA con cuDNN de NVIDIA correspondiente sobre Ubuntu 22.04 — cuda-12.4 a partir de nvidia/cuda:12.4.1-cudnn-runtime-ubuntu22.04. Las imágenes son solo amd64, lo que coincide con la flota: los hosts de Superheat son x86_64.

La nomenclatura cuda-<minor> es también contra lo que se resuelve la etiqueta [Automatic] de una plantilla. Dejar la etiqueta de una plantilla como [Automatic] elige la etiqueta más reciente cuya CUDA pueda ejecutar la máquina elegida, así que una misma plantilla funciona en una flota con controladores dispares. Fije una etiqueta concreta cuando necesite que una compilación sea reproducible en lugar de actual.

Qué agrega

Sobre el runtime de CUDA: openssh-server, python3 con pip y jupyterlab, tini, gosu, openssl, ca-certificates, curl, git y rsync. El directorio de trabajo es /workspace y el entrypoint es tini -- /opt/superheat/entrypoint.sh.

La imagen lleva la etiqueta com.superheat.base="true". Esa etiqueta es la forma en que Superheat reconoce una imagen como utilizable para los modos ssh y jupyter, y la hereda todo lo que usted construya FROM la base.

Qué hace el entrypoint

Cada paso es idempotente, así que detener e iniciar una instancia lo vuelve a ejecutar sin riesgo sobre el mismo contenedor.

Paso	Detalle
1. Exportar el entorno	El entorno del contenedor se escribe en /etc/environment y /etc/profile.d/superheat-env.sh, porque sshd y Jupyter lanzan shells de login que no lo heredan. Los secretos de aprovisionamiento se excluyen.
2. Instalar las claves	PUBLIC_KEY y SUPERHEAT_SSH_PUBLIC_KEYS se escriben en /root/.ssh/authorized_keys.
3. Iniciar sshd	Las claves de host se generan si faltan, y luego sshd escucha en el puerto 22 del contenedor. Solo por clave; no se aceptan contraseñas.
4. Iniciar Jupyter	Solo cuando JUPYTER_TOKEN está definido. Se genera una vez un certificado autofirmado y JupyterLab se enlaza a 0.0.0.0:${JUPYTER_PORT} sobre HTTPS.
5. Ejecutar onstart	SUPERHEAT_ONSTART se ejecuta una vez, protegido por un centinela. Un fallo se registra y el contenedor sigue en pie.
6. Ceder el control	Se ejecuta el CMD de la imagen si lo hay; si no, el contenedor queda inactivo para seguir en ejecución de cara al mapa de puertos.

El contrato de entorno

Estos nombres de variable son el cable entre Superheat y la imagen. Construya sobre la base y el entrypoint las respeta por usted; construya su propio entrypoint y esto es lo que tendrá que implementar.

Variable	Propósito
PUBLIC_KEY	Una sola clave pública OpenSSH, que se agrega a authorized_keys
SUPERHEAT_SSH_PUBLIC_KEYS	Claves públicas OpenSSH separadas por saltos de línea, que se agregan a authorized_keys
SUPERHEAT_ONSTART	Bash que se ejecuta una vez en el primer arranque. Es sensible; no se persiste en los archivos de entorno. También se acepta el alias simple ONSTART
JUPYTER_TOKEN	Cuando está definida, JupyterLab arranca con este valor como su token de acceso
JUPYTER_PORT	Puerto de escucha de Jupyter, 8080 de forma predeterminada
JUPYTER_DIR	Directorio raíz de Jupyter, /workspace de forma predeterminada
JUPYTER_LAB	true para JupyterLab (predeterminado), false para el notebook clásico
OPEN_BUTTON_PORT	Informativa — el puerto destino del botón Abrir de la consola
CONTAINER_ID	Informativa — el identificador de la carga de trabajo
GPU_COUNT	Informativa — cuántas GPU están asignadas
SUPERHEAT_TCP_PORT_<n>	Informativa — el puerto del host publicado para el puerto de contenedor <n>

Superheat define estas al final, después del entorno de su plantilla y de cualquier sustitución del arrendatario, así que ninguna de ellas puede quedar eclipsada. Consulte Variables de entorno.

Construir su propia imagen

Herede de la etiqueta cuya CUDA coincida con la que necesita su código, instale sus dependencias y no toque el entrypoint:

FROM superheat/base:cuda-12.4

RUN pip install --no-cache-dir torch torchvision transformers

COPY train.py /workspace/train.py
WORKDIR /workspace

Tres reglas mantienen el resultado lanzable en los modos ssh y jupyter:

1. Herede, no reconstruya. Construir desde nvidia/cuda y copiar dentro su propio sshd pierde la etiqueta com.superheat.base y, con ella, el contrato del entrypoint.
2. No sobrescriba ENTRYPOINT. El entrypoint base es lo que arranca sshd, Jupyter y su script de inicio. Sobrescribirlo convierte una plantilla ssh en un contenedor sin forma de entrar.
3. Ponga su proceso en CMD. El entrypoint ejecuta CMD después del aprovisionamiento, así que un servidor de larga duración iniciado de esa forma tiene sshd y Jupyter a su lado.

Si su imagen no puede seguir esas reglas — una imagen upstream que usted no controla, o una con un entrypoint propio — use el modo de lanzamiento args en su lugar. Ejecuta el entrypoint nativo de cualquier imagen y no necesita nada de la base. Consulte Modos de lanzamiento.

De qué etiqueta heredar

Situación	Etiqueta
Su framework fija una versión menor de CUDA	la cuda-<minor> correspondiente
Quiere la CUDA más reciente disponible y puede reconstruir	latest
Necesita que una compilación se resuelva igual dentro de meses	la etiqueta sha-…

Fijar una etiqueta cuda-<minor> es la respuesta habitual. latest se mueve cuando se publica una nueva versión menor de CUDA, lo que está bien para una imagen de desarrollo y es una mala base para una ejecución de entrenamiento reproducible.

Estructura del sistema de archivos

Ruta	Contenido
/workspace	El directorio de trabajo y, de forma predeterminada, la raíz de Jupyter
/opt/superheat/entrypoint.sh	El entrypoint de aprovisionamiento
/var/lib/superheat/onstart.sh	El cuerpo del script de inicio tal como se ejecutó
/var/lib/superheat/.onstart-done	El centinela que impide que el script de inicio se vuelva a ejecutar
/var/log/superheat/onstart.log	La salida del script de inicio
/var/log/superheat/jupyter.log	La salida de Jupyter
/etc/profile.d/superheat-env.sh	El entorno tal como lo ven los shells de login

sshd y Jupyter también envían su salida al log del contenedor, que es lo que muestra la consola. Consulte Leer los logs.