Ejemplo con Docker

Esta página muestra una configuración reproducible con Docker para ejecutar un escenario .pmod de AugeLab Studio en modo headless.

La imagen se construye localmente a partir de un Dockerfile. Los clientes no necesitan el código fuente de AugeLab Studio. El contenedor instala el paquete cerrado studio desde el índice de paquetes de AugeLab durante la construcción de la imagen.

Requisitos previos

• Docker Desktop o Docker Engine con Docker Compose.

• Acceso al índice de paquetes de AugeLab.

• Un código de verificación de AugeLab.

• Un escenario .pmod que pueda ejecutarse sin interfaz (headless).

• Para GPU/CUDA: NVIDIA Container Toolkit instalado en el host.

Camino rápido

1. Crea la estructura de carpetas que se muestra abajo.

2. Pon tu archivo .pmod en app/.

3. Añade tu código de verificación en .env.

4. Usa el Dockerfile para CPU o para GPU según necesites.

5. Ejecuta docker compose up --build.

6. Revisa la carpeta output_on_host.

Estructura del proyecto

augelab-docker-example/
  .env
  docker-compose.yml
  docker-compose.cuda.yml
  output_on_host/
  app/
    Dockerfile
    Dockerfile.cuda
    run_scenario.py
    your_scenario.pmod

Sustituye your_scenario.pmod por tu propio archivo de escenario.

Archivo de entorno

Crea .env junto a docker-compose.yml:

.env

AUGELAB_VERIFICATION_CODE=PASTE_YOUR_VERIFICATION_CODE_HERE
SCENARIO_PATH=your_scenario.pmod

No hagas commit de .env si contiene un código de verificación real.

Ejecutor del escenario

Crea app/run_scenario.py:

app/run_scenario.py

import os
from pathlib import Path

from studio import StudioScenario


OUTPUT_DIR = Path("/app/app_output")
OUTPUT_DIR.mkdir(parents=True, exist_ok=True)

verification_code = os.environ.get("AUGELAB_VERIFICATION_CODE")
if not verification_code:
    raise RuntimeError("AUGELAB_VERIFICATION_CODE is not set.")

scenario_path = os.environ.get("SCENARIO_PATH", "your_scenario.pmod")
if not Path(scenario_path).is_file():
    raise FileNotFoundError(f"Scenario file not found: {scenario_path}")

scenario = StudioScenario(verification_code=verification_code)
scenario.enable_logging_stdout()
scenario.load_scenario(scenario_path)

try:
    print("Scenario result:", scenario.run())
finally:
    scenario.cleanup()

Si tu escenario escribe archivos, configúralo para que los escriba bajo /app/app_output.

Dockerfile para CPU

Usa este para ejecuciones headless en CPU.

app/Dockerfile

FROM python:3.12-slim-bookworm

WORKDIR /app

RUN apt-get update -y && \
    apt-get install -y --no-install-recommends \
    libdmtx0b \
    zbar-tools \
    build-essential \
    libgl1-mesa-glx \
    curl \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

ADD https://astral.sh/uv/0.9.17/install.sh /uv-installer.sh
RUN sh /uv-installer.sh && rm /uv-installer.sh

ENV PATH="/root/.local/bin/:$PATH"

RUN uv pip install studio --system \
    --extra-index-url https://pyrepo.augelab.com \
    --extra-index-url https://download.pytorch.org/whl/cpu \
    --index-strategy unsafe-best-match

RUN python -c "from studio import StudioScenario; print('studio import ok')"

COPY run_scenario.py .
COPY your_scenario.pmod .

CMD ["python", "run_scenario.py"]

Dockerfile para GPU/CUDA

Usa este cuando tu escenario necesite aceleración CUDA. El host debe tener controladores NVIDIA compatibles y NVIDIA Container Toolkit.

app/Dockerfile.cuda

FROM nvidia/cuda:12.8.0-cudnn-runtime-ubuntu22.04

WORKDIR /app

RUN apt-get update -y && \
    apt-get install -y --no-install-recommends \
    python3 \
    python3-venv \
    python3-pip \
    libdmtx0b \
    zbar-tools \
    build-essential \
    libgl1-mesa-glx \
    curl \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

ADD https://astral.sh/uv/0.9.17/install.sh /uv-installer.sh
RUN sh /uv-installer.sh && rm /uv-installer.sh

ENV PATH="/root/.local/bin/:$PATH"
ENV NVIDIA_VISIBLE_DEVICES=all
ENV NVIDIA_DRIVER_CAPABILITIES=compute,utility

RUN uv pip install "studio[gpu]" --system \
    --extra-index-url https://pyrepo.augelab.com \
    --index-strategy unsafe-best-match

RUN python3 -c "from studio import StudioScenario; print('studio gpu import ok')"

COPY run_scenario.py .
COPY your_scenario.pmod .

CMD ["python3", "run_scenario.py"]

Archivo de Compose

Usa este para el Dockerfile de CPU:

docker-compose.yml

services:
  augelab-headless:
    build:
      context: ./app
      dockerfile: Dockerfile
    env_file:
      - .env
    volumes:
      - ./output_on_host:/app/app_output

Esto monta ./output_on_host desde tu carpeta del proyecto dentro del contenedor en /app/app_output.

⚠️ En Windows, usa barras inclinadas hacia adelante en rutas absolutas para montajes de Docker, por ejemplo C:/work/augelab_output:/app/app_output. Los montajes relativos como ./output_on_host:/app/app_output suelen ser más fáciles de compartir entre máquinas.

Compose para GPU/CUDA

Usa este para Dockerfile.cuda:

docker-compose.cuda.yml

services:
  augelab-headless-gpu:
    build:
      context: ./app
      dockerfile: Dockerfile.cuda
    env_file:
      - .env
    volumes:
      - ./output_on_host:/app/app_output
    gpus: all

Construir y ejecutar

CPU:

docker compose up --build

GPU/CUDA:

docker compose -f docker-compose.cuda.yml up --build

Deberías ver los logs de AugeLab Studio y el resultado del escenario en la terminal.

Verificar la salida

Revisa output_on_host en tu máquina host. Los archivos escritos por el escenario en /app/app_output deberían aparecer allí.

Solución de problemas

Problema	Verifica
Fallo al instalar studio	Confirma acceso a la red y al índice de paquetes de AugeLab.
Fallo de licencia/activación	Confirma que AUGELAB_VERIFICATION_CODE está establecido y que el contenedor tiene acceso a Internet.
Archivo de escenario no encontrado	Confirma que SCENARIO_PATH coincide con el .pmod copiado por el Dockerfile.
Carpeta de salida vacía	Confirma que el .pmod escribe en /app/app_output.
Volumen en Windows no se monta	Usa barras inclinadas hacia adelante y confirma que Docker Desktop puede acceder a la unidad.
Contenedor GPU no detecta la GPU	Instala NVIDIA Container Toolkit y prueba con docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu22.04 nvidia-smi.