mirror of
https://github.com/retspen/webvirtcloud
synced 2026-10-18 00:50:07 +00:00
docs: translate dependency upgrade plan to English and update milestones
This commit is contained in:
catborise
parent
2b402992b4
commit
21873ffdc9
1 changed files with 150 additions and 68 deletions
|
|
@ -1,85 +1,167 @@
|
||||||
# WebVirtCloud - Bağımlılık ve Kütüphane Güncelleme Planı
|
# WebVirtCloud - Dependency Upgrade & Modernization 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.
|
This document outlines the dependency audit, completed technical debt resolution, and future modernization roadmap for the WebVirtCloud project. It covers Python 3.12/3.13 compatibility, framework migrations, frontend libraries, and container base images.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 1. Tespit Edilen Kütüphaneler ve Durum Analizi
|
## 1. Executive Summary & Compatibility Status
|
||||||
|
|
||||||
### 1.1. Kritik ve Acil Müdahale Gerektirenler (Python 3.12+ Uyumsuzlukları)
|
WebVirtCloud has historically relied on libraries established during the Python 3.8 - 3.10 era. Recent efforts have systematically eliminated obsolete dependencies and removed breaking Python 3.12 incompatibilities.
|
||||||
|
|
||||||
| Kütüphane / Dosya | Mevcut Durum | Risk Seviyesi | Tespit ve Sorun |
|
### Current Compatibility Baseline
|
||||||
|
|
||||||
|
| Component | Target Version | Status |
|
||||||
|
|---|---|---|
|
||||||
|
| **Python** | 3.10, 3.11, 3.12, 3.13 | ✅ Verified on 3.10–3.12; 3.13 ready (`crypt-r` conditional) |
|
||||||
|
| **Operating Systems** | Ubuntu 22.04/24.04, Debian 12, Rocky/RHEL 9/10 | ✅ Validated across modern enterprise Linux distros |
|
||||||
|
| **Django** | 4.2.23 (LTS) | ✅ Active (Supported through April 2026) |
|
||||||
|
| **OpenAPI / Swagger** | OpenAPI 3.0 (`drf-spectacular`) | ✅ Replaced legacy Swagger 2.0 (`drf-yasg`) |
|
||||||
|
| **Container Base** | `phusion/baseimage:noble-1.0.2` (Ubuntu 24.04 LTS) | ✅ Upgraded from Jammy (22.04) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Completed Milestones & Resolved Technical Debt
|
||||||
|
|
||||||
|
The following table summarizes items that have been fully resolved in the codebase:
|
||||||
|
|
||||||
|
| Component / File | Previous State | Current State | Impact & Resolution |
|
||||||
|---|---|---|---|
|
|---|---|---|---|
|
||||||
| **`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. |
|
| **`vrtManager/rwlock.py`** | Used removed `threading.currentThread()` | Updated to `threading.current_thread()` | **Critical Bugfix**: Resolved fatal `ImportError` on Python 3.12+. |
|
||||||
| **`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. |
|
| **`rwlock==0.0.7`** | Listed in `conf/requirements.txt` | **Removed** | **Cleanup**: Package was abandoned in 2014; codebase uses local `vrtManager/rwlock.py`. |
|
||||||
| **`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. |
|
| **`vrtManager/IPy.py`** | 1,650 lines of vendored IPy 1.01 (2011) | Replaced with stdlib `ipaddress` | **Maintenance**: Removed unmaintained legacy code, improved IP parsing performance, and added 15 regression unit tests. |
|
||||||
| **`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. |
|
| **`console/novncd` & `socketiod`** | Used deprecated `optparse` | Migrated to standard `argparse` | **Modernization**: Full CLI argument parsing compliance with modern Python standard library. |
|
||||||
|
| **API Documentation** | `drf-yasg==1.21.10` (Swagger 2.0) | Migrated to `drf-spectacular[sidecar]==0.28.0` | **Modernization**: Upgraded to OpenAPI 3.0 with offline/air-gapped Swagger UI and Redoc sidecar assets. |
|
||||||
|
| **`Dockerfile` Base Image** | `phusion/baseimage:jammy-1.0.1` (Ubuntu 22.04) | `phusion/baseimage:noble-1.0.2` (Ubuntu 24.04 LTS) | **Infrastructure**: Brings modern system libraries (`libvirt 10.0+`, OpenSSL 3.0+, GCC 13+). |
|
||||||
|
| **Bootstrap** | Bootstrap 5.2.2 | Upgraded to Bootstrap 5.3.3 | **Frontend**: CSS variables support, form accessibility improvements, and dark mode foundations. |
|
||||||
|
| **Python 3.13 Crypt Support** | Stdlib `crypt` module removed in 3.13 | `crypt-r>=3.13.0; python_version >= "3.13"` | **Future-proofing**: Added conditional fallback dependency for root password hashing in `vrtManager/create.py`. |
|
||||||
|
| **LDAP Dependency** | Unconditional `python-ldap` import | Optional / graceful degradation | **Cross-Platform**: WebVirtCloud boots cleanly on minimal hosts without requiring C-header LDAP compilation. |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 1.2. Django & API Ekosistemi
|
## 3. Pending & Future Roadmap
|
||||||
|
|
||||||
| Kütüphane | Mevcut Sürüm | Hedef Sürüm | Açıklama & Strateji |
|
The following tasks represent future upgrade phases prioritized by maintenance schedules and architectural value.
|
||||||
|
|
||||||
|
### 3.1. Django 5.x LTS Roadmap (Django 4.2 LTS -> Django 5.2 LTS)
|
||||||
|
|
||||||
|
- **Priority**: High (Before April 2026)
|
||||||
|
- **Current State**: Django `4.2.23` LTS (supported until April 2026).
|
||||||
|
- **Target State**: Django `5.2` LTS (scheduled for release in April 2025 with support through April 2028).
|
||||||
|
|
||||||
|
#### Action Items:
|
||||||
|
1. **Retire `django-login-required-middleware`**:
|
||||||
|
- The third-party package `django-login-required-middleware==0.9.0` has not been updated since 2017.
|
||||||
|
- Django 5.1 introduced native `django.contrib.auth.middleware.LoginRequiredMiddleware`.
|
||||||
|
- Once upgraded to Django 5.1+, remove the third-party package from `INSTALLED_APPS`, `MIDDLEWARE`, and `requirements.txt`.
|
||||||
|
2. **Deprecation Warnings Audit**:
|
||||||
|
- Run test suite with `-Wd` flag to identify deprecated features prior to stepping to 5.x.
|
||||||
|
- Verify compatibility of all database backends (SQLite, MySQL/MariaDB, PostgreSQL).
|
||||||
|
3. **Form Rendering and Async ORM**:
|
||||||
|
- Leverage Django 5 form field templates and expanded async ORM capabilities where appropriate.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3.2. Asynchronous Console Architecture: `eventlet` Evaluation
|
||||||
|
|
||||||
|
- **Priority**: Medium / Long-term
|
||||||
|
- **Current State**: `socketiod` utilizes `eventlet==0.40.1` for WebSocket concurrency.
|
||||||
|
- **Risk Analysis**:
|
||||||
|
- `eventlet` is in minimal maintenance and relies on monkey-patching CPython primitives.
|
||||||
|
- Python 3.12 and 3.13 changes to internal frames and `greenlet` have historically produced runtime instability with monkey-patching frameworks.
|
||||||
|
- **Proposed Architecture**:
|
||||||
|
- Evaluate migrating `socketiod` to modern ASGI or asyncio-native WebSocket architectures (e.g., standard Python `websockets`, `aiohttp`, or Django Channels).
|
||||||
|
- Alternatively, evaluate encapsulating console proxying within a lightweight dedicated gateway (e.g., Go/Rust WebSocket proxy or native Nginx WebSocket passthrough).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3.3. noVNC Modernization (1.5.0+)
|
||||||
|
|
||||||
|
- **Priority**: Medium
|
||||||
|
- **Current State**: Vendored noVNC assets in `static/js/novnc/` date from the 2020 release.
|
||||||
|
- **Target State**: noVNC `1.5.0` or latest stable release.
|
||||||
|
- **Benefits**:
|
||||||
|
- Robust auto-reconnect logic on transient network loss.
|
||||||
|
- Enhanced mobile and touch-screen trackpad / gesture emulation.
|
||||||
|
- Performance improvements in canvas rendering via modern WebGL/Canvas APIs.
|
||||||
|
- Improved clipboard and audio streaming support.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3.4. Frontend Maintenance: jQuery Update
|
||||||
|
|
||||||
|
- **Priority**: Low / Maintenance
|
||||||
|
- **Current State**: `jQuery 3.6.1` (bundled in `static/js/jquery.min.js`).
|
||||||
|
- **Target State**: `jQuery 3.7.1`.
|
||||||
|
- **Benefits**:
|
||||||
|
- Bug fixes in selector parsing and event delegation.
|
||||||
|
- Elimination of known CVEs in legacy utility methods.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Phase-by-Phase Execution Timeline
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TD
|
||||||
|
subgraph Completed ["Phase 1: Completed Milestones"]
|
||||||
|
C1["Python 3.12 thread fix (rwlock.py)"]
|
||||||
|
C2["Eradicate IPy.py -> stdlib ipaddress"]
|
||||||
|
C3["CLI optparse -> argparse"]
|
||||||
|
C4["drf-yasg -> drf-spectacular"]
|
||||||
|
C5["Docker Base -> Ubuntu 24.04 (Noble)"]
|
||||||
|
C6["Bootstrap -> 5.3.3"]
|
||||||
|
C7["Python 3.13 crypt-r conditional"]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Phase2 ["Phase 2: Frontend & Client Refresh"]
|
||||||
|
P2A["Update jQuery 3.6.1 -> 3.7.1"]
|
||||||
|
P2B["Modernize noVNC client to 1.5.0+"]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Phase3 ["Phase 3: Django 5.x LTS Migration"]
|
||||||
|
P3A["Upgrade Django 4.2 LTS to 5.2 LTS"]
|
||||||
|
P3B["Replace django-login-required-middleware with native Django 5.1 middleware"]
|
||||||
|
P3C["Audit deprecations and run full test matrix"]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Phase4 ["Phase 4: Async WebSocket Gateway"]
|
||||||
|
P4A["Profile socketiod under Python 3.12/3.13"]
|
||||||
|
P4B["Design ASGI / asyncio-native replacement for eventlet"]
|
||||||
|
end
|
||||||
|
|
||||||
|
Completed --> Phase2
|
||||||
|
Phase2 --> Phase3
|
||||||
|
Phase3 --> Phase4
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Support & Compatibility Matrix
|
||||||
|
|
||||||
|
| Distribution / Environment | Python Version | Libvirt Python | Status |
|
||||||
|---|---|---|---|
|
|---|---|---|---|
|
||||||
| **`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. |
|
| **Ubuntu 22.04 LTS (Jammy)** | 3.10 | 8.0.0+ | Fully Supported |
|
||||||
| **`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. |
|
| **Ubuntu 24.04 LTS (Noble)** | 3.12 | 10.0.0+ | Fully Supported (Recommended Docker Base) |
|
||||||
| **`drf-yasg`** | `1.21.10` | `drf-spectacular` ✅ | Terk edilmiş Swagger 2.0 kütüphanesi yerine modern OpenAPI 3.0 standardı olan **`drf-spectacular`** (sidecar ile offline/air-gapped destekli) kuruldu. |
|
| **Debian 12 (Bookworm)** | 3.11 | 9.0.0+ | Fully Supported |
|
||||||
| **`IPy.py`** (`vrtManager/IPy.py`) | Vendored 1.01 (2011) | Python Standard `ipaddress` ✅ | 1650+ satırlık eski harici kod silindi, standart `ipaddress` modülüne geçildi ve 15 adet unit test eklendi. |
|
| **Rocky Linux / RHEL 9** | 3.9 / 3.11 | 9.0.0+ | Fully Supported |
|
||||||
|
| **Rocky Linux / RHEL 10** | 3.12 | 11.0.0+ | Fully Supported |
|
||||||
|
| **Docker (Production Image)** | 3.12 (Noble base) | Bundled | Primary Supported Container Target |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 1.3. Ön Yüz (Frontend) ve VNC İstemcisi
|
## 6. Verification and CI Guidelines
|
||||||
|
|
||||||
| Kütüphane | Mevcut Sürüm | Güncel Sürüm | Yenilikler & Faydalar |
|
Whenever dependencies are upgraded, the following verification pipeline must pass:
|
||||||
|---|---|---|---|
|
|
||||||
| **`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. **Syntax & Unit Tests**:
|
||||||
|
```bash
|
||||||
### 1.4. Altyapı ve Konteyner
|
pytest
|
||||||
|
# or
|
||||||
| Bileşen | Mevcut Durum | Önerilen Durum | Açıklama |
|
python3 manage.py test
|
||||||
|---|---|---|---|
|
```
|
||||||
| **`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. **Schema & Check Validations**:
|
||||||
|
```bash
|
||||||
---
|
python3 manage.py check --deploy
|
||||||
|
python3 manage.py spectacular --file /tmp/schema.yml --validate
|
||||||
## 2. Aşamalı Güncelleme Yol Haritası (Migration Roadmap)
|
```
|
||||||
|
3. **Multi-Platform CI**:
|
||||||
### Aşama 1: Hızlı Kazanımlar ve Python 3.12+ Uyumluluğu (Hemen Yapılabilir)
|
- Ensure GitHub Actions workflow (`.github/workflows/linter.yml` and testing workflows) run on Python 3.10, 3.11, and 3.12.
|
||||||
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ş.
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue