q-buffer/README.md

q-buffer

q-buffer, qBittorrent üzerinde torrentleri kontrollü şekilde döngüye almayı ve peer kısıtlamasını otomatikleştirmeyi amaçlayan bir uygulamadır. Buffer ekranında torrent seçip loop akışını başlatabilir, Timer ekranında etiket bazlı otomatik silme kuralları tanımlayabilirsiniz.

Neler yapar?

• qBittorrent WebUI API ile bağlanır, aktif torrent listesini gösterir.
• Seçilen torrent için loop (indir → sil → yeniden ekle) işlemini yönetir.
• Allow IP kuralıyla agresif peer kısıtlaması uygular (destek varsa ban).
• Timer kurallarıyla etiket bazlı seed süresi dolan torrentleri otomatik siler.
• Gerçek zamanlı durum, log ve metrikleri UI üzerinden gösterir.

Hızlı Başlangıç

1. .env.example dosyasını .env olarak kopyalayın ve değerleri doldurun.
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:

./scripts/bootstrap.sh --dev-mode

4. Açın:

• Web: http://localhost:5173
• API/Socket: http://localhost:3001

Watcher Notu

Watcher akışı wscraper -> scrapling -> Playwright zincirini kullanır. Playwright DNS ve browser bağımlılıklarını Docker içine taşımak yerine wscraper-service host makinede çalışır; web ve server ise Docker içinde kalır. server, host servisle http://host.docker.internal:8787 üzerinden konuşur.

bootstrap.sh şu işleri tek komutta yapar:

• Docker servislerini up --build ile kaldırır
• host wscraper-service için Python venv hazırlar
• eksik Python paketlerini ve Playwright bağımlılıklarını kurar
• wscraper-servicei başlatır

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:

./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:

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:

./scripts/bootstrap.sh --dev-mode
./scripts/bootstrap.sh --prod-mode
./scripts/bootstrap.sh --dev-mode --skip-wscraper-install
./scripts/bootstrap.sh --dev-mode --restart-wscraper

Docker tarafında normal ağ erişimi hâlâ gereklidir. DNS problemi yaşarsanız Docker Desktop içinde sabit resolver (8.8.8.8, 1.1.1.1) tanımlayın. Docker DNS doğru ayarlanmamışsa:

• pnpm install
• image pull işlemleri
• container içi paket kurulumları

kurulum sırasında kırılabilir.

Önerilen Docker Engine ayarı:

{
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  },
  "experimental": false,
  "dns": ["8.8.8.8", "1.1.1.1"]
}

Docker Desktop yeniden başladıktan sonra şu testler başarılı olmalıdır:

docker run --rm alpine nslookup registry-1.docker.io
docker run --rm alpine nslookup files.pythonhosted.org
docker run --rm alpine nslookup cdn.playwright.dev

Host servis için kullanılacak ortam değişkenleri:

• WSCRAPER_SERVICE_BASE_URL varsayılan: http://host.docker.internal:8787
• WSCRAPER_SERVICE_TOKEN varsayılan: boş
• WSCRAPER_SERVICE_HOST varsayılan: 0.0.0.0
• 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

Kullanım (Buffer)

1. qBittorrent’te torrentleri ekleyin (UI listeye düşer).
2. Loop yapmak istediğiniz torrent için listede upload ikonuna tıklayın ve .torrent dosyasını seçin.
   • Bu işlem torrent dosyasını arşivler.
   • Arşiv yüklenmeden Loop Setup başlamaz.
3. Allow IP, Loop sayısı ve Delay değerlerini girip Start’a basın.

Kullanım (Timer)

1. Etiketleri qBittorrent’te oluşturun (radarr, tv-sonarr gibi).
2. Timer ekranında etiket seçip seed süresi kuralı ekleyin.
3. Süresi dolan torrentler qBittorrent ve diskten silinir.

Production

./scripts/bootstrap.sh --prod-mode

Ardından http://localhost:3001

Ortam Değişkenleri

• QBIT_BASE_URL, QBIT_USERNAME, QBIT_PASSWORD
• APP_USERNAME, APP_PASSWORD, JWT_SECRET
• POLL_INTERVAL_MS, ENFORCE_INTERVAL_MS, DEFAULT_DELAY_MS, MAX_LOOP_LIMIT
• WEB_ALLOWED_HOSTS (ör: localhost,qbuffer.bee,qbuffer.panda)
• WSCRAPER_SERVICE_BASE_URL, WSCRAPER_SERVICE_TOKEN

Klasör Yapısı

• apps/server: Express API + socket.io
• apps/web: Vite React UI
• data: JSON DB, loglar, arşivlenen torrent dosyaları