> 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/french/key-features/headless/docker-example.md).

# Exemple Docker

Cette page montre une configuration Docker reproductible pour exécuter sans interface (headless) un scénario AugeLab Studio au format `.pmod`.

L'image est construite localement à partir d'un Dockerfile. Les clients n'ont pas besoin du code source d'AugeLab Studio. Le conteneur installe le paquet propriétaire `studio` depuis l'index de paquets AugeLab lors de la construction de l'image.

## Prérequis

* Docker Desktop ou Docker Engine avec Docker Compose.
* Accès à l'index de paquets AugeLab.
* Un code de vérification AugeLab.
* Un scénario `.pmod` pouvant s'exécuter en headless.
* Pour GPU/CUDA : NVIDIA Container Toolkit installé sur la machine hôte.

## Chemin rapide

1. Créez la structure de dossiers ci-dessous.
2. Placez votre fichier `.pmod` dans `app/`.
3. Ajoutez votre code de vérification dans `.env`.
4. Choisissez le Dockerfile CPU ou GPU.
5. Exécutez `docker compose up --build`.
6. Vérifiez le dossier `output_on_host`.

## Structure du projet

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

Remplacez `your_scenario.pmod` par votre propre fichier de scénario.

## Fichier d'environnement

Créez `.env` à côté de `docker-compose.yml` :

<details>

<summary>.env</summary>

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

</details>

Ne commitez pas `.env` s'il contient un vrai code de vérification.

## Exécuteur de scénario

Créez `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 votre scénario écrit des fichiers, configurez-le pour qu'il les écrive sous `/app/app_output`.

## Dockerfile CPU

Utilisez celui-ci pour des exécutions headless sur 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 GPU/CUDA

Utilisez celui-ci si votre scénario a besoin d'accélération CUDA. L'hôte doit avoir des pilotes NVIDIA compatibles et NVIDIA Container Toolkit installé.

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

## Fichier Compose

Utilisez ceci pour le Dockerfile 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>

Cela monte `./output_on_host` depuis votre dossier de projet dans le conteneur en tant que `/app/app_output`.

> Attention : sur Windows, utilisez des slashs avant (forward slashes) pour les chemins de montage Docker absolus, par exemple `C:/work/augelab_output:/app/app_output`. Les montages relatifs comme `./output_on_host:/app/app_output` sont généralement plus faciles à partager entre machines.

## Compose pour GPU/CUDA

Utilisez ceci pour `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>

## Construction et exécution

CPU :

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

GPU/CUDA :

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

Vous devriez voir les logs d'AugeLab Studio et le résultat du scénario dans le terminal.

## Vérifier la sortie

Consultez `output_on_host` sur votre machine hôte. Les fichiers écrits par le scénario dans `/app/app_output` devraient apparaître là.

## Dépannage

| Problème                            | Vérifier                                                                                                                       |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| installation de `studio` échoue     | Confirmez l'accès réseau et l'accès à l'index de paquets AugeLab.                                                              |
| Licence/activation échoue           | Confirmez que `AUGELAB_VERIFICATION_CODE` est défini et que le conteneur a accès à Internet.                                   |
| Fichier de scénario introuvable     | Confirmez que `SCENARIO_PATH` correspond au `.pmod` copié par le Dockerfile.                                                   |
| Dossier de sortie vide              | Confirmez que le `.pmod` écrit dans `/app/app_output`.                                                                         |
| Volume Windows non monté            | Utilisez des slashs avant et confirmez que Docker Desktop peut accéder au disque.                                              |
| Le conteneur GPU ne voit pas le GPU | Installez NVIDIA Container Toolkit et testez avec `docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu22.04 nvidia-smi`. |