From 2860bda260a3f3886278d95fce92a60ac1130b59 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 13 Dec 2025 22:08:26 +0000 Subject: [PATCH] Update documentation for modern Python virtual environment approach Co-authored-by: ShaYmez <76499782+ShaYmez@users.noreply.github.com> --- CHANGELOG.md | 13 +++++++++++++ README.md | 14 +++++++++++++- 2 files changed, 26 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bea1272..4b81ca0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Changed +- **BREAKING CHANGE - Modern Python Package Management**: For Debian 12+ (Bookworm/Trixie), HBMonv2 now uses a Python virtual environment instead of system-wide package installation +- HBMonv2 Python dependencies installed in isolated virtual environment at `/opt/HBMonv2/venv` for Debian 12+ +- pip_install helper function now uses virtual environment for Debian 12+ (PEP 668 compliant) +- systemd service file automatically configured to use virtual environment Python interpreter for Debian 12+ +- Added python3-venv to system dependencies for Debian 12+ - Enhanced pip_install helper function with comprehensive error handling and user feedback - Added proper error checking after all pip package installations - Improved error messages to help users diagnose installation failures @@ -14,10 +19,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Changed deprecated --force flag to --force-reinstall for attrs package installation ### Fixed +- **Resolved externally-managed-environment errors on Debian 12/13** by using virtual environments instead of --break-system-packages flag +- **Resolved package conflicts with system-installed cryptography** by isolating Python packages in virtual environment - Silent pip installation failures now properly reported to users - Missing requirements.txt file now handled gracefully with warning instead of silent failure - pip installation errors now cause the installer to exit with proper error messages +### Technical Details +- Debian 10-11: Continues to use standard system-wide pip installation (backward compatible) +- Debian 12+: Uses modern virtual environment approach following PEP 668 standards +- Virtual environment is automatically activated during installation +- pip is upgraded within the virtual environment for latest features + ## [1.5.0] - 2024-12-13 ### Verified diff --git a/README.md b/README.md index 6e0cb78..c2af85a 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ ======= This is a multi-arch docker installer for HBlink3 and HBmonV2 combined for Debian 10, 11, 12, and 13 (Trixie). -**Note:** Debian 12 (Bookworm) and 13 (Trixie) support has been added with proper handling of pip installation restrictions and docker-compose compatibility. See [CHANGELOG.md](CHANGELOG.md) for version history and updates. +**Note:** Debian 12 (Bookworm) and 13 (Trixie) support has been added with proper PEP 668 compliant Python package management using virtual environments, and docker-compose compatibility. HBMonv2 now runs in an isolated Python virtual environment on Debian 12+. See [CHANGELOG.md](CHANGELOG.md) for version history and updates. ![HBlink](img/HBLINK_logoV1.png "HBlink") @@ -140,6 +140,18 @@ Within this installation includes the new HBMonv2 by Weldek SP2ONG * Includes lastheard database with auto cron installed * Includes talkgroup html editable page +### Technical Details - Python Package Management + +**Debian 12+ (Bookworm/Trixie):** The installer uses modern Python package management following PEP 668 standards: +- HBMonv2 runs in an isolated Python virtual environment at `/opt/HBMonv2/venv` +- All Python dependencies are installed within this virtual environment, avoiding system-wide package conflicts +- The systemd service automatically uses the virtual environment's Python interpreter +- This approach eliminates "externally-managed-environment" errors and conflicts with system packages + +**Debian 10-11:** Standard pip installation to system Python is used for backward compatibility. + +This ensures clean, maintainable installations that follow modern Python best practices while maintaining compatibility with older Debian versions. + ## Easy Installation And Upgrade The installation can be upgraded either by the use of a future scripts or by manually backing up your configuration and re-running the install script. Also the ability and really cool feature of docker-compose is that its easy to update the container with fresh images! Run by a simple command. Make sure you are in the /etc/hblink3 dir. ```sh