> 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/turkish/temel-ozellikler/headless/docker-example.md).

# Docker Örneği

Bu sayfa, AugeLab Studio `.pmod` senaryosunu başsız (headless) çalıştırmak için tekrarlanabilir bir Docker kurulumu gösterir.

İmaj, bir Dockerfile'dan yerel olarak oluşturulur. Müşterilerin AugeLab Studio kaynak koduna ihtiyacı yoktur. Container, imaj oluşturma sırasında kapalı kaynak `studio` paketini AugeLab paket dizininden kurar.

## Önkoşullar

* Docker Desktop veya Docker Engine ile Docker Compose.
* AugeLab paket dizinine erişim.
* Bir AugeLab doğrulama kodu.
* Başsız çalıştırılabilecek bir `.pmod` senaryosu.
* GPU/CUDA için: host üzerine NVIDIA Container Toolkit kurulmuş olmalı.

## Hızlı yol

1. Aşağıdaki klasör düzenini oluşturun.
2. `.pmod` dosyanızı `app/` içine koyun.
3. Doğrulama kodunuzu `.env` dosyasına ekleyin.
4. CPU veya GPU Dockerfile'ını kullanın.
5. `docker compose up --build` komutunu çalıştırın.
6. `output_on_host` klasörünü kontrol edin.

## Proje dizini

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

`your_scenario.pmod` öğesini kendi senaryo dosyanızın adıyla değiştirin.

## Ortam dosyası

`docker-compose.yml` dosyasının yanına `.env` oluşturun:

<details>

<summary>.env</summary>

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

</details>

Gerçek bir doğrulama kodu içeriyorsa `.env` dosyasını sürüm kontrolüne (commit) eklemeyin.

## Senaryo çalıştırıcı

`app/run_scenario.py` dosyasını oluşturun:

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

Eğer senaryonuz dosya yazıyorsa, çıktıların `/app/app_output` altında yazıldığından emin olun.

## CPU Dockerfile

Standart başsız CPU çalıştırmaları için bunu kullanın.

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

## GPU/CUDA Dockerfile

Senaryonuz CUDA hızlandırmasına ihtiyaç duyuyorsa bunu kullanın. Host'ta uygun NVIDIA sürücüleri ve NVIDIA Container Toolkit olmalıdır.

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

## Compose dosyası

CPU Dockerfile için kullanın:

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

Bu, proje klasörünüzdeki `./output_on_host` klasörünü container içinde `/app/app_output` olarak bağlar (mount).

{% hint style="warning" %}
Windows üzerinde, mutlak Docker mount yollarında ileri eğik çizgi (forward slash) kullanın; örneğin `C:/work/augelab_output:/app/app_output`. Göreli mount'lar (`./output_on_host:/app/app_output`) genellikle makineler arası paylaşım için daha kolaydır.
{% endhint %}

## GPU/CUDA compose dosyası

`Dockerfile.cuda` için kullanın:

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

## Derleme ve çalıştırma

CPU:

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

GPU/CUDA:

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

Terminalde AugeLab Studio loglarını ve senaryo sonucunu görmelisiniz.

## Çıktıyı doğrulama

Host makinenizde `output_on_host` klasörünü kontrol edin. Senaryonun `/app/app_output` içine yazdığı dosyalar burada görünmelidir.

## Sorun Giderme

| Problem                             | Kontrol edin                                                                                                                              |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `studio` kurulumu başarısız oluyor  | Ağ erişimini ve AugeLab paket dizinine erişimi doğrulayın.                                                                                |
| Lisans/aktivasyon başarısız         | `AUGELAB_VERIFICATION_CODE` değişkeninin ayarlı olduğunu ve container'ın internet erişimi olduğunu doğrulayın.                            |
| Senaryo dosyası bulunamıyor         | `SCENARIO_PATH` değerinin Dockerfile ile kopyalanan `.pmod` ile eşleştiğini doğrulayın.                                                   |
| Çıktı klasörü boş                   | `.pmod` dosyasının çıktıları `/app/app_output` içine yazdığından emin olun.                                                               |
| Windows üzerinde volume bağlanmıyor | İleri eğik çizgi kullandığınızdan emin olun ve Docker Desktop'ın sürücüyü erişime açtığını doğrulayın.                                    |
| GPU container GPU'yu göremiyor      | NVIDIA Container Toolkit'i kurun ve `docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu22.04 nvidia-smi` ile testi gerçekleştirin. |