diff --git a/.gitignore b/.gitignore index 8860fff..bc289ab 100644 --- a/.gitignore +++ b/.gitignore @@ -17,3 +17,4 @@ webvirtcloud/settings.py htmlcov *.log templates/webvirtcloud.code-workspace +DEPENDENCY_UPGRADE_PLAN.md diff --git a/DEPENDENCY_UPGRADE_PLAN.md b/DEPENDENCY_UPGRADE_PLAN.md deleted file mode 100644 index 8abf0d9..0000000 --- a/DEPENDENCY_UPGRADE_PLAN.md +++ /dev/null @@ -1,167 +0,0 @@ -# WebVirtCloud - Dependency Upgrade & Modernization Plan - -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. Executive Summary & Compatibility Status - -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. - -### 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`** | Used removed `threading.currentThread()` | Updated to `threading.current_thread()` | **Critical Bugfix**: Resolved fatal `ImportError` on Python 3.12+. | -| **`rwlock==0.0.7`** | Listed in `conf/requirements.txt` | **Removed** | **Cleanup**: Package was abandoned in 2014; codebase uses local `vrtManager/rwlock.py`. | -| **`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. | -| **`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. | - ---- - -## 3. Pending & Future Roadmap - -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 | -|---|---|---|---| -| **Ubuntu 22.04 LTS (Jammy)** | 3.10 | 8.0.0+ | Fully Supported | -| **Ubuntu 24.04 LTS (Noble)** | 3.12 | 10.0.0+ | Fully Supported (Recommended Docker Base) | -| **Debian 12 (Bookworm)** | 3.11 | 9.0.0+ | Fully Supported | -| **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 | - ---- - -## 6. Verification and CI Guidelines - -Whenever dependencies are upgraded, the following verification pipeline must pass: - -1. **Syntax & Unit Tests**: - ```bash - pytest - # or - python3 manage.py test - ``` -2. **Schema & Check Validations**: - ```bash - python3 manage.py check --deploy - python3 manage.py spectacular --file /tmp/schema.yml --validate - ``` -3. **Multi-Platform CI**: - - Ensure GitHub Actions workflow (`.github/workflows/linter.yml` and testing workflows) run on Python 3.10, 3.11, and 3.12. diff --git a/CODEBASE_OVERVIEW.md b/doc/architecture.md similarity index 100% rename from CODEBASE_OVERVIEW.md rename to doc/architecture.md