# IBKR Dashboard Operasyon Rehberi

Bu rehber, projeyi yerelde Docker ile baslatmak, saglik kontrolu yapmak, smoke test calistirmak ve guvenli sekilde kapatmak icin kisa bir operasyon akisi verir.

## 1. Onkosullar

- Docker Desktop calisiyor olmali.
- Docker icin repo kokunde `docker.env` dosyasi olmali.
- Lokal Python calismalari icin isterseniz ayri bir `.env` dosyasi tutabilirsiniz.
- `.env` icindeki `WEBHOOK_SECRET` varsayilan degerde birakilmamali.
- Docker secret dosyalari `./secrets` altinda olusturulmali.

## 2. Hazirlik

`docker.env.example` dosyasini `docker.env` olarak kopyalayin. Ardindan gerekli secret dosyalarini olusturun:

```bash
cp docker.env.example docker.env
mkdir -p secrets
printf '%s\n' 'your_ibkr_password' > secrets/tws_password
printf '%s\n' 'change_this_webhook_secret' > secrets/webhook_secret

chmod 600 secrets/tws_password secrets/webhook_secret

docker network inspect traefik-public >/dev/null 2>&1 || docker network create traefik-public
```

Notlar:

- `primaryoverride`, mevcut bir IBKR oturumu varsa gateway'in login dialogunda takilma riskini azaltir.
- Uygulama SQLite veritabani icin `./data` dizinini kullanir. Dizin repo icinde mevcut olmali.
- Opsiyonel secret dosyalari: `secrets/vnc_password`, `secrets/ui_username`, `secrets/ui_password`.

## 3. Stack Baslatma

Servisleri build edip arka planda kaldirin:

```bash
docker compose --env-file docker.env up -d --build
```

Durumu kontrol edin:

```bash
docker compose --env-file docker.env ps -a
```

Beklenen durum:

- `ib-gateway`: `Up (healthy)`
- `ibkr-dashboard`: `Up` veya kisa sure sonra `Up (healthy)`

Log takibi icin:

```bash
docker compose --env-file docker.env logs -f ib-gateway ibkr-dashboard
```

## 4. Health Kontrolu

Uygulama health endpoint'ini dogrulayin:

```bash
curl -sS --max-time 10 http://localhost:8000/health
```

Beklenen cevap ornegi:

```json
{"status":"ok","ib_connected":true,"account":"...","db_ok":true,"version":"3.0"}
```

`status=ok`, `ib_connected=true` ve `db_ok=true` gorulmelidir.

## 5. Test ve Smoke Dogrulama

Offline test paketi:

```bash
pytest tests/ -q --tb=short
```

Beklenen sonuc:

```text
47 passed, 2 skipped
```

Docker smoke testi:

```bash
./verify_docker.sh
```

Guncel dogrulanmis durum:

- Script 18/18 check geciyor.

Canli IB entegrasyon testlerini ozellikle acmak isterseniz:

```bash
RUN_LIVE_IB_TESTS=1 pytest tests/test_integration.py -q --tb=short
```

## 6. Sorun Giderme

### Docker Compose `$` warning'i

Semptom:

```text
The "K4" variable is not set. Defaulting to a blank string.
```

Cozum:

- Compose komutlarini `.env.docker.tmp` ile calistirin.
- Docker icin `docker compose --env-file docker.env ...` kullanin.
- Secret degerlerini `./secrets` altindaki dosyalardan okuyun.

### Gateway login oluyor ama healthy olmuyor

Kontrol edin:

```bash
docker compose --env-file docker.env logs --tail=100 ib-gateway
```

Beklenen satirlar:

- `Login has completed`
- `Configuration tasks completed`

### Dashboard ayaga kalkmiyor

Kontrol edin:

```bash
docker compose --env-file docker.env logs --tail=100 ibkr-dashboard
```

Ozellikle su hatalara bakin:

- `sqlite3.OperationalError: unable to open database file`
- `TimeoutError` veya IB gateway baglanti hatalari

## 7. Kapatma

Servisleri temiz kapatmak icin:

```bash
docker compose --env-file docker.env down --remove-orphans
```

Docker secret dosyalarini yerinde birakip sadece `docker.env` kaldirilabilir:

```bash
rm -f docker.env
```

## 8. Operasyon Notlari

- `verify_docker.sh`, varsayilan olarak `docker.env` varsa onu kullanir; yoksa `.env`'e geri duser.
- Docker ic aginda dashboard, gateway'e `ib-gateway:4004` uzerinden baglanir.
- Host makinede paper API erisimi `127.0.0.1:4002`, live API erisimi `127.0.0.1:4001` olarak map edilir.

## 9. Geriye Donuk Fallback

Eger mevcut `.env` ile devam etmek zorundaysaniz, eski gecici dosya akisi hala kullanilabilir:

```bash
sed 's/\$/\$\$/g' .env > .env.docker.tmp
COMPOSE_ENV_FILE=.env.docker.tmp COMPOSE_APP_ENV_FILE=.env.docker.tmp ./verify_docker.sh
```