From e29b68c5d7279e9c6b10af3b4fddf0469b694978 Mon Sep 17 00:00:00 2001
From: wisecolt <wisecolt@gmail.com>
Date: Fri, 13 Mar 2026 02:27:12 +0300
Subject: [PATCH] docs: watcher kurulum akisini netlestir

---
 README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 67 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 067f7e5..39b43e4 100644
--- a/README.md
+++ b/README.md
@@ -13,13 +13,14 @@ q-buffer, qBittorrent üzerinde torrentleri kontrollü şekilde döngüye almay
 ## Hızlı Başlangıç
 
 1) `.env.example` dosyasını `.env` olarak kopyalayın ve değerleri doldurun.
-2) Geliştirme ortamını başlatın:
+2) İlk kurulumda `wscraper-service` tarafını okuyun: `Watcher` özelliği için host makinede Python 3.10+ gerekir.
+3) Geliştirme ortamını başlatın:
 
 ```bash
 ./scripts/bootstrap.sh --dev-mode
 ```
 
-3) Açın:
+4) Açın:
 
 - Web: http://localhost:5173
 - API/Socket: http://localhost:3001
@@ -37,6 +38,66 @@ q-buffer, qBittorrent üzerinde torrentleri kontrollü şekilde döngüye almay
 
 `wscraper-service` kurulumu her çalıştırmada sıfırdan yapılmaz. Kurulum daha önce tamamlandıysa script sadece kontrol eder ve eksik yoksa yeniden kurmaz.
 
+### İlk Kurulumda wscraper Yapılandırması
+
+Bu bölüm ilk kez `q-buffer` kuranlar içindir. Sık karışan nokta şu:
+
+- `bin/wscraper/` dizini scraper paketinin kendisidir
+- `bin/wscraper-service/server.py`, `q-buffer` backend'in çağırdığı host servisidir
+- yani `wscraper` dizininde yalnızca `server.py` yok; asıl tracker adapter kodları `bin/wscraper/src/wscraper/...` altındadır
+
+Mevcut geçici kurulum modeli:
+
+- önce `q-buffer` repo clone edilir
+- sonra `wscraper` repo ayrıca clone edilir
+- clone edilen `wscraper` kodu `q-buffer/bin/wscraper` altına yerleştirilir
+
+Yani yeni bir makinede yalnızca `q-buffer` clone etmek şu an yeterli değildir; `wscraper` kaynak kodunun da ayrıca gelmesi gerekir.
+
+İlk kurulum adımları:
+
+1. `q-buffer` repo'yu clone edin.
+2. `wscraper` repo'yu ayrıca clone edin ve `q-buffer/bin/wscraper` altına yerleştirin.
+3. `.env.example` dosyasını `.env` olarak kopyalayın.
+4. qBittorrent ve uygulama auth ayarlarını doldurun.
+5. watcher servis ayarlarını kontrol edin:
+   - `WSCRAPER_SERVICE_BASE_URL=http://host.docker.internal:8787`
+   - `WSCRAPER_SERVICE_TOKEN=` boş bırakılabilir
+   - `WSCRAPER_SERVICE_HOST=0.0.0.0`
+   - `WSCRAPER_SERVICE_PORT=8787`
+   - `WSCRAPER_SERVICE_PYTHON_BIN=python3.12`
+6. `q-buffer/bin/wscraper` altında şu dosyaların geldiğini doğrulayın:
+   - `pyproject.toml`
+   - `setup.py`
+   - `src/wscraper/cli.py`
+   - `src/wscraper/sites/happyfappy.py`
+   - `src/wscraper/sites/privatehd.py`
+7. Host makinede uygun Python sürümü olduğundan emin olun:
+   - `python3.12 --version`
+   - yoksa `python3.11` veya `python3.10`
+8. Repo root'ta şu komutu çalıştırın:
+
+```bash
+./scripts/bootstrap.sh --dev-mode
+```
+
+Bu komut şunları yapar:
+
+- Docker `web` ve `server` servislerini `up --build` ile başlatır
+- host'ta `.runtime/wscraper-service/.venv` oluşturur
+- `scrapling[fetchers]` kurar
+- `scrapling install` çalıştırır
+- `bin/wscraper-service/server.py` sürecini başlatır
+
+Kurulumdan sonra kontrol edilecekler:
+
+```bash
+curl http://127.0.0.1:8787/health
+docker compose -f docker-compose.dev.yml ps
+```
+
+İlk komutta `{"ok":true,...}` benzeri cevap, ikinci komutta `server` ve `web` container'ları görülmelidir.
+
 Host makinede Python 3.10+ gerekir. Script sırasıyla `python3.12`, `python3.11`, `python3.10`, `python3` ikililerini dener ve uygun ilk sürümü seçer. Gerekirse `.env` içine `WSCRAPER_SERVICE_PYTHON_BIN=python3.12` benzeri açık bir değer verebilirsiniz.
 
 Kullanılabilir bayraklar:
@@ -87,6 +148,10 @@ Host servis için kullanılacak ortam değişkenleri:
 - `WSCRAPER_SERVICE_PORT` varsayılan: `8787`
 - `WSCRAPER_SERVICE_PYTHON_BIN` örnek: `python3.12`
 
+Daha detaylı `wscraper` dökümü için:
+
+- [bin/wscraper/README.md](/Users/wisecolt-macmini/Project/q-buffer/bin/wscraper/README.md)
+
 ## Kullanım (Buffer)
 
 1) qBittorrent’te torrentleri ekleyin (UI listeye düşer).