docs: add codebase overview and dependency upgrade plan

CODEBASE_OVERVIEW.md

@@ -0,0 +1,169 @@
+# WebVirtCloud - Kod Tabanı İnceleme ve Mimari Dokümantasyonu
+
+Bu doküman, **WebVirtCloud** projesinin mimari yapısını, temel bileşenlerini, veri akışını ve modüller arası ilişkilerini açıklamak amacıyla hazırlanmıştır.
+
+---
+
+## 1. Genel Tanım ve Amacı
+
+**WebVirtCloud**, QEMU/KVM tabanlı hipervizörlerin ve bu hipervizörler üzerinde koşan sanal makinelerin (VM/Instance) web tabanlı arayüz ve REST API aracılığıyla yönetilmesini sağlayan açık kaynaklı bir sanallaştırma yönetim platformudur.
+
+Platform, hem sistem yöneticilerine birden fazla fiziksel KVM sunucusunu tek noktadan yönetme imkânı sunar, hem de son kullanıcılara kendilerine atanan sanal makineleri kontrol etme (başlatma, durdurma, yeniden başlatma, konsol erişimi, snapshot alma, kaynak izleme) yetkisi tanır.
+
+---
+
+## 2. Teknoloji Yığını (Tech Stack)
+
+| Katman | Teknoloji / Kütüphane | Açıklama |
+|---|---|---|
+| **Çalışma Zamanı** | Python >= 3.11 | Modern Python çalışma ortamı |
+| **Web Çatısı** | Django 4.2 LTS | MVC tabanlı ana web altyapısı ve ORM |
+| **API** | Django REST Framework (DRF) + drf-yasg | RESTful API uçları ve Swagger/OpenAPI dokümantasyonu |
+| **Sanallaştırma API** | `libvirt-python` (11.4.0) + `lxml` | Libvirt API çağrıları ve XML domain/storage/network tanımlamaları |
+| **Konsol / VNC** | WebSockify + noVNC | Web tarayıcısı üzerinden HTML5 VNC/SPICE konsol erişimi |
+| **Ön Yüz (Frontend)** | Django Templates, Bootstrap 5, Bootstrap Icons, jQuery | Sunucu taraflı render edilen dinamik kullanıcı arayüzü |
+| **Kimlik & Güvenlik** | Django Auth, `django-otp` (2FA/TOTP), `django-auth-ldap` | Rol bazlı yetkilendirme, 2 faktörlü doğrulama, LDAP/Active Directory desteği |
+| **Web / WSGI Sunucu** | Nginx + Gunicorn + WhiteNoise | Statik dosya dağıtımı ve ters vekil sunucu mimarisi |
+| **Süreç Yöneticisi** | Supervisor / Runit / Systemd | Gunicorn ve novncd arka plan servislerinin yönetimi |
+
+---
+
+## 3. Sistem Mimarisi ve Temel Katmanlar
+
+```
+                               +-----------------------------+
+                               |     Web Tarayıcısı / İstemci |
+                               +--------------+--------------+
+                                              |
+                       HTTP / HTTPS (Port 80/443)   WebSockets (Port 6080)
+                                              |              |
+                                              v              v
++------------------------------------------------------------------------------------+
+| Nginx Reverse Proxy                                                                |
+|   ├── /static/  --> Statik Dosyalar (WhiteNoise / Nginx)                           |
+|   ├── /         --> Gunicorn (Django WSGI Application)                             |
+|   └── :6080     --> WebSockify (novncd arka plan servisi)                         |
++-------------------------------------+----------------------------------------------+
+                                      |
+                                      v
++------------------------------------------------------------------------------------+
+| Django Uygulama Katmanı (WebVirtCloud)                                             |
+|                                                                                    |
+|  [accounts]      Kullanıcılar, Roller, Kotalar, SSH Keyler, 2FA, LDAP             |
+|  [computes]      Hipervizör (Compute Node) bağlantı tanımları                     |
+|  [instances]     Sanal makine modelleri, yaşam döngüsü, migrate, flavor            |
+|  [storages]      Storage havuzları ve disk hacimleri (dir, lvm, rbd/ceph vb.)     |
+|  [networks]      Sanal ağlar (NAT, isolated, bridge vb.)                           |
+|  [interfaces]    Fiziksel / köprü ağ arayüzleri                                    |
+|  [nwfilters]     Ağ filtreleme ve güvenlik duvarı kuralları                        |
+|  [virtsecrets]   Libvirt gizli anahtarları (Ceph auth vb.)                        |
+|  [datasource]    Cloud-init metadata / userdata servisleri                        |
+|  [logs]          Kullanıcı ve sistem işlem denetim kayıtları (audit log)          |
+|  [api/v1]        DRF Nested Routers ile REST API uçları                            |
++-------------------------------------+----------------------------------------------+
+                                      |
+                                      v
++------------------------------------------------------------------------------------+
+| vrtManager Katmanı (Libvirt Abstraction Engine)                                    |
+|   ├── connection.py  --> TCP, SSH, TLS veya yerel Socket ile Libvirt bağlantısı    |
+|   ├── instance.py    --> XML Domain üretimi, CPU/RAM/Disk/Snapshot/Metrics         |
+|   ├── storage.py     --> Storage pool & volume XML yönetimi                        |
+|   ├── network.py     --> Network XML konfigürasyonu ve IP yönetimi                 |
+|   └── hostdetails.py --> Node info, bellek ve CPU kullanım metrikleri             |
++-------------------------------------+----------------------------------------------+
+                                      |
+                       Libvirt Protokolü (TCP/SSH/TLS/Socket)
+                                      |
+                                      v
++------------------------------------------------------------------------------------+
+| KVM / QEMU Hipervizör Sunucuları                                                   |
+|   ├── libvirtd / virtqemud                                                         |
+|   ├── QEMU Guest Domainleri (VMs) + QEMU Guest Agent                               |
+|   └── Storage & Network Altyapısı (ZFS, LVM, Ceph RBD, Linux Bridge, OVS)          |
++------------------------------------------------------------------------------------+
+```
+
+---
+
+## 4. Modüller ve Dizin Yapısı Analizi
+
+### 4.1. `vrtManager/` (Çekirdek Libvirt Motoru)
+Projenin en kritik Python paketidir. Django modelleri veritabanında hipervizörlerin durumlarını statik tutmak yerine, libvirt ile doğrudan canlı haberleşir.
+- **`connection.py`**: Farklı bağlantı tipleri (`CONN_TCP`, `CONN_SSH`, `CONN_TLS`, `CONN_SOCKET`) üzerinden libvirt bağlantı havuzunu (`connection_manager`) yönetir. Eşzamanlı erişimler için `ReadWriteLock` kullanır.
+- **`instance.py`**: `wvmInstance` sınıfı aracılığıyla sanal makinelerin başlatılması, kapatılması, duraklatılması, yeniden başlatılması, CPU/RAM boyutlandırması, disk ekleme/çıkarma, XML düzenleme, snapshot işlemleri ve anlık donanım istatistiklerini (vCPU, ağ I/O, disk I/O) çeker.
+- **`create.py`**: XML şablonlarını dinamik üreterek yeni sanal makineler oluşturan motor.
+- **`storage.py` & `network.py`**: Depolama havuzları (dir, lvm, iscsi, rbd/ceph) ve libvirt sanal ağlarının yönetimini üstlenir.
+- **`hostdetails.py`**: Hipervizörün toplam bellek, CPU kullanımı ve donanım mimarisi bilgilerini sağlar.
+
+### 4.2. `computes/` (Hipervizör Yönetimi)
+- Hipervizör ana makine (host) kayıtlarını barındırır (`hostname`, `login`, `password`, `type`).
+- Canlı bağlantı nesnesini `connection_manager` üzerinden lazy olarak temin eder (`cached_property`).
+- REST API üzerinden mimarileri (`archs`), işlemci ve bellek durumlarını dışa aktarır.
+
+### 4.3. `instances/` (Sanal Makine Yönetimi)
+- **`Instance` Modeli**: Sanal makinenin `compute` ilişkisini, benzersiz `uuid` değerini ve `name` bilgisini saklar. Dinamik tüm durumlar (durum, bellek, vcpu, diskler, ağ kartları vb.) `vrtManager.instance.wvmInstance` vekili (proxy) üzerinden okunur.
+- **`Flavor` Modeli**: AWS EC2 veya OpenStack benzeri hazır boyut şablonlarını (vcpu, ram, disk) tanımlar.
+- **`MigrateInstance`**: Sanal makinelerin canlı (live), çevrimdışı (offline), sıkıştırmalı (compressed) veya güvensiz (unsafe) yöntemlerle başka bir compute host'a taşınmasını sağlar.
+- **`views.py`**: VM oluşturma sihirbazı, düzenleme, klonlama, snapshot ve güç kontrollerini içerir.
+
+### 4.4. `accounts/` (Kullanıcılar, İzinler ve Kotalar)
+- Standart Django `User` modeline ek olarak:
+  - **`UserInstance`**: Kullanıcıya belirli bir VM üzerinde okuma, değiştirme (`is_change`), silme (`is_delete`) ve konsol açma (`is_vnc`) yetkilerini delege eder.
+  - **`UserAttributes`**: Kullanıcı bazında kota belirler (Maksimum VM adedi, maksimum vCPU, maksimum RAM ve maksimum disk boyutu).
+  - **`UserSSHKey`**: Kullanıcının VM'lere otomatik enjekte edilecek açık anahtarlarını depolar.
+  - İki faktörlü kimlik doğrulama (TOTP/QR) ve opsiyonel LDAP/AD senkronizasyonunu yönetir.
+
+### 4.5. `console/` (Uzak Konsol Erişimi)
+- **`novncd`**: Python tabanlı WebSockify uygulamasını çalıştırarak tarayıcıdaki noVNC istemcisi ile KVM üzerindeki VNC/SPICE portu arasında WebSocket köprüsü kurar.
+- **`sshtunnels.py`**: Compute host uzak bir sunucuda ise ve doğrudan VNC portu dışarıya açık değilse, güvenli SSH tüneli açarak konsol bağlantısını yerel sokete yönlendirir.
+
+### 4.6. `datasource/` (Cloud-Init Desteği)
+- Cloud-init uyumlu bir HTTP metadata/userdata sunucusudur.
+- VM ilk açıldığında `http://<webvirtcloud>/datasource/` adresine istek atar.
+- İstemci IP'sinden hostname ve VM adı çözülerek, VM sahibine ait SSH açık anahtarları `user-data` şablonu halinde VM'e teslim edilir. Böylece şifresiz SSH erişimi otomatik ayarlanır.
+
+### 4.7. `storages/`, `networks/`, `interfaces/`, `nwfilters/`, `virtsecrets/`
+- **`storages`**: Dizin, LVM, NFS, iSCSI ve Ceph RBD depolama havuzları oluşturma, ISO yükleme, disk hacmi (volume) klonlama ve silme.
+- **`networks`**: NAT, Routed, Bridge ve Isolated sanal ağ oluşturma, DHCP havuzu ve statik IP/MAC eşleme.
+- **`interfaces`**: Fiziksel host ağ arayüzlerini ve köprüleri (bridges) listeleme ve yönetme.
+- **`nwfilters`**: MAC/IP sahteciliğini önleyen (anti-spoofing) ve paket filtreleyen kuralları yönetme.
+- **`virtsecrets`**: Özellikle Ceph kimlik doğrulaması için gereken Libvirt secret tanımlarını yönetme.
+
+### 4.8. `logs/` & `appsettings/` & `admin/`
+- **`logs`**: Hangi kullanıcının hangi instance üzerinde ne zaman ne işlem yaptığını (güç açma, kapatma, disk ekleme vb.) kaydeden denetim günlüğü.
+- **`appsettings`**: Veritabanı üzerinde dinamik olarak uygulama parametrelerini (site başlığı, izinler vb.) saklar ve context processor ile arayüze taşır.
+- **`admin`**: Kullanıcı, grup ve genel sistem yönetim paneli.
+
+---
+
+## 5. REST API Mimarisi (`/api/v1/`)
+
+Django REST Framework (`drf-nested-routers`) kullanılarak hiyerarşik bir kaynak yapısı kurgulanmıştır:
+
+- `/api/v1/computes/` : Hipervizör listesi ve yönetimi
+  - `/api/v1/computes/{id}/instances/` : İlgili hipervizördeki sanal makineler
+  - `/api/v1/computes/{id}/instances/create/{arch}/{machine}/` : Yeni sanal makine oluşturma
+  - `/api/v1/computes/{id}/networks/` : Sanal ağlar
+  - `/api/v1/computes/{id}/interfaces/` : Ağ arayüzleri
+  - `/api/v1/computes/{id}/storages/` : Depolama havuzları
+    - `/api/v1/computes/{id}/storages/{id}/volumes/` : Depolama birimleri (diskler)
+  - `/api/v1/computes/{id}/archs/` : Desteklenen mimariler
+- `/api/v1/instances/` : Genel sanal makine listesi
+- `/api/v1/flavor/` : Boyut şablonları
+- `/api/v1/migrate/` : Sanal makine taşıma operasyonları
+- `/swagger/` & `/redoc/` : Canlı API dokümantasyonu
+
+---
+
+## 6. Dağıtım ve Servis Yaşam Döngüsü
+
+1. **Gunicorn**: WSGI uygulaması olarak `webvirtcloud.wsgi:application` çalışır (Port: Nginx unix socket veya 8000).
+2. **novncd**: Arka planda çalışarak VNC/SPICE portlarını `6080` portundan WebSocket'e çevirir.
+3. **Nginx**: 80/443 portlarından dış dünyayı karşılar, statik dosyaları sunar, dinamik istekleri Gunicorn'a, VNC WebSocket trafiğini ise `novncd` servisine iletir.
+4. **Supervisor / Runit**: Docker ortamında (`Dockerfile`) Phusion BaseImage tabanlı runit kullanılırken, standart Linux sunucularında Supervisor veya Systemd servisleri kullanılır.
+
+---
+
+## 7. Özet Değerlendirme
+
+WebVirtCloud, **Django ORM**'in gücünü doğrudan **libvirt C API binding'leri** ile hibrit şekilde birleştiren, veritabanında sadece temel ilişkileri tutup asıl durum ve metrikleri gerçek zamanlı olarak doğrudan sanallaştırma katmanından okuyan esnek ve hafif bir yönetim panelidir.

DEPENDENCY_UPGRADE_PLAN.md

@@ -0,0 +1,85 @@
+# WebVirtCloud - Bağımlılık ve Kütüphane Güncelleme Planı
+
+Bu doküman, WebVirtCloud projesinde yer alan eski, desteği kesilmiş veya yeni Python/Django sürümleriyle uyumsuzluk riski taşıyan kütüphanelerin tespitini ve adım adım güncelleme yol haritasını içermektedir.
+
+---
+
+## 1. Tespit Edilen Kütüphaneler ve Durum Analizi
+
+### 1.1. Kritik ve Acil Müdahale Gerektirenler (Python 3.12+ Uyumsuzlukları)
+
+| Kütüphane / Dosya | Mevcut Durum | Risk Seviyesi | Tespit ve Sorun |
+|---|---|---|---|
+| **`vrtManager/rwlock.py`** | `currentThread()` kullanımı | 🔴 **Kritik (Bozucu)** | Python 3.10'da kullanımdan kaldırılmış (deprecated), **Python 3.12'de tamamen silinmiştir**. Python 3.12 üzerinde `ImportError: cannot import name 'currentThread' from 'threading'` hatası verir. `threading.current_thread()` ile değiştirilmelidir. |
+| **`rwlock==0.0.7`** (`conf/requirements.txt`) | 2014 sürümü (Terk edilmiş) | 🟡 **Gereksiz Bağımlılık** | Projede kod zaten `vrtManager/rwlock.py` üzerinden yerel (vendored) çalışmaktadır. `requirements.txt` içerisindeki bu harici paket gereksizdir ve temizlenebilir. |
+| **`console/novncd` & `socketiod` (`optparse`)** | `optparse` kullanımı | 🟠 **Orta (Kullanımdan Kaldırıldı)** | `optparse` Python 3.2'den beri deprecated olup yerini standart `argparse` kütüphanesine bırakmıştır. Modern Python standartlarına göre refactor edilmelidir. |
+| **`eventlet==0.40.1`** | `socketiod` içinde kullanılır | 🟠 **Yüksek Risk** | Eventlet, Python 3.12+ C-API ve greenlet değişiklikleriyle uyumluluk sorunları yaşamaktadır. Gelecekte asyncio/ASGI mimarisine geçiş planlanmalıdır. |
+
+---
+
+### 1.2. Django & API Ekosistemi
+
+| Kütüphane | Mevcut Sürüm | Hedef Sürüm | Açıklama & Strateji |
+|---|---|---|---|
+| **`Django`** | `4.2.23` (LTS) | `5.1.x` / `5.2` (LTS) | Django 4.2 LTS desteği Nisan 2026'da sona ermektedir. Django 5.x LTS'e yükseltme yapılarak performans kazanımları (asenkron ORM geliştirmeleri, yeni form alanları) elde edilmelidir. |
+| **`django-login-required-middleware`** | `0.9.0` (2017) | **Kaldırılacak** (Native) | Paket 2017'den beri güncellenmemiştir. **Django 5.1 ile birlikte Django artık yerleşik `django.contrib.auth.middleware.LoginRequiredMiddleware` sunmaktadır.** Harici paket tamamen devreden çıkarılabilir. |
+| **`drf-yasg`** | `1.21.10` | `drf-spectacular` | `drf-yasg` fiilen terk edilmiştir, yalnızca eski Swagger 2.0 standardını destekler ve Django 5+ ile uyumsuzluk uyarıları verir. DRF'in resmi olarak önerdiği modern OpenAPI 3.0 standardı olan **`drf-spectacular`**'a geçilmelidir. |
+| **`IPy.py`** (`vrtManager/IPy.py`) | Vendored 1.01 (2011) | Python Standard `ipaddress` | Projede yer alan 1600 satırlık harici `IPy.py` dosyası yerine, Python 3.3+'dan beri yerleşik olan standart `ipaddress` modülü kullanılmalıdır. |
+
+---
+
+### 1.3. Ön Yüz (Frontend) ve VNC İstemcisi
+
+| Kütüphane | Mevcut Sürüm | Güncel Sürüm | Yenilikler & Faydalar |
+|---|---|---|---|
+| **`jQuery`** | `3.6.1` (2022) | `3.7.1` | Güvenlik yamaları, seçici (selector) optimizasyonları ve hata düzeltmeleri. |
+| **`Bootstrap`** | `5.2.2` (2022) | `5.3.3` | Yerel Karanlık Mod (Dark Mode) desteği, CSS değişkenleri mimarisi, erişilebilirlik ve form iyileştirmeleri. |
+| **`noVNC`** (`static/js/novnc`) | 2020 Sürümü | `1.5.0` | Çok daha kararlı WebSocket yeniden bağlanma (auto-reconnect), dokunmatik ekran desteği, güvenlik düzeltmeleri ve modern ES modül yapısı. |
+
+---
+
+### 1.4. Altyapı ve Konteyner
+
+| Bileşen | Mevcut Durum | Önerilen Durum | Açıklama |
+|---|---|---|---|
+| **`Dockerfile` Base Image** | `phusion/baseimage:jammy-1.0.1` (Ubuntu 22.04) | `phusion/baseimage:noble-1.0.0` (Ubuntu 24.04 LTS) | Ubuntu 24.04 LTS tabanına geçilerek daha yeni sistem kütüphaneleri (`libvirt`, `openssl`, `gcc`) temin edilebilir. |
+
+---
+
+## 2. Aşamalı Güncelleme Yol Haritası (Migration Roadmap)
+
+### Aşama 1: Hızlı Kazanımlar ve Python 3.12+ Uyumluluğu (Hemen Yapılabilir)
+1. **`vrtManager/rwlock.py` Düzeltmesi**:
+   - `currentThread()` çağrılarını `current_thread()` ile değiştirerek Python 3.12'deki kritik çökme riskini ortadan kaldırmak.
+2. **`requirements.txt` Temizliği**:
+   - Kullanılmayan `rwlock==0.0.7` paketini `conf/requirements.txt` dosyasından silmek.
+3. **Frontend Kütüphanelerinin Güncellenmesi**:
+   - `jQuery` 3.6.1 -> 3.7.1
+   - `Bootstrap` 5.2.2 -> 5.3.3
+
+---
+
+### Aşama 2: API ve Dokümantasyon Modernizasyonu (Orta Vadeli)
+1. **Swagger / OpenAPI Göçü**:
+   - `drf-yasg` yerine `drf-spectacular` kurulumu.
+   - `webvirtcloud/urls.py` ve `urls-api.py` rotalarının OpenAPI 3.0 şemasına güncellenmesi.
+2. **CLI Argümanları Refactor**:
+   - `console/novncd` ve `console/socketiod` içerisindeki `optparse` yerine standart `argparse` modülünün entegre edilmesi.
+
+---
+
+### Aşama 3: Django 5.x LTS Geçişi (Büyük Sürüm Güncellemesi)
+1. **LoginRequiredMiddleware Değişimi**:
+   - `django-login-required-middleware` paketinin kaldırılması.
+   - Django 5.1+'ın yerleşik `django.contrib.auth.middleware.LoginRequiredMiddleware` sınıfına geçilmesi.
+2. **Django 4.2 -> 5.1/5.2 Yükseltmesi**:
+   - `conf/requirements.txt` içinde Django sürümünün artırılması.
+   - `python3 manage.py check` ve test suitinin (`pytest` / `python manage.py test`) koşturularak deprecation uyarılarının temizlenmesi.
+
+---
+
+### Aşama 4: noVNC ve Ağ Modülleri Optimizasyonu
+1. **noVNC 1.5.0 Entegrasyonu**:
+   - `static/js/novnc/` klasörünün noVNC 1.5.0 resmi sürümüyle yenilenmesi.
+2. **`vrtManager/IPy.py` Refactor**:
+   - Harici IPy kütüphanesi yerine standart `ipaddress` kütüphanesine geçiş.