> For the complete documentation index, see [llms.txt](https://docs.augelab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.augelab.com/spanish/caracteristicas-clave/headless/docker-example.md).

# 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`:

<details>

<summary>.env</summary>

```env
AUGELAB_VERIFICATION_CODE=PASTE_YOUR_VERIFICATION_CODE_HERE
SCENARIO_PATH=your_scenario.pmod
```

</details>

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

## Ejecutor del escenario

Crea `app/run_scenario.py`:

<details>

<summary>app/run_scenario.py</summary>

```python
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()
```

</details>

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.

<details>

<summary>app/Dockerfile</summary>

```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"]
```

</details>

## Dockerfile para GPU/CUDA

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

<details>

<summary>app/Dockerfile.cuda</summary>

```dockerfile
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"]
```

</details>

## Archivo de Compose

Usa este para el Dockerfile de CPU:

<details>

<summary>docker-compose.yml</summary>

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

</details>

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`:

<details>

<summary>docker-compose.cuda.yml</summary>

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

</details>

## Construir y ejecutar

CPU:

```bash
docker compose up --build
```

GPU/CUDA:

```bash
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`. |