hblink3-docker-install/CHANGELOG.md

Changelog

All notable changes to the hblink3-docker-install project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.5.1] - 2025-12-14

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
• Added directory verification before installing from requirements.txt
• 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

Release Information

• Docker upstream repository version: 2.0.2
• Docker version: alpine-3.20
• Installer version: 1.5.1 (14122024)
• Full Debian 11, 12, 13 and Ubuntu 22.04, 24.04 LTS support confirmed

[1.5.0] - 2024-12-13

Verified

• Full Debian 13 (Trixie) support confirmed working (33/33 tests passed)
• Upstream repository compatibility verified:
  • hblink3: https://github.com/ShaYmez/hblink3 (accessible, recently updated for Debian compatibility)
  • HBMonv2: https://github.com/ShaYmez/HBMonv2 (accessible, all dependencies compatible)
• pip installation with --break-system-packages flag working correctly for Debian 12+
• docker-compose-plugin installation working correctly for Debian 12+
• All control scripts validated (syntax and functionality)
• Version detection logic confirmed for Debian 13
• Documentation accurately references Debian 13 (Trixie) support

Added

• CHANGELOG.md to track project changes and releases

[1.4.0] - 2024-12-13

Note

This version corresponds to installer version 13122025

Added

• Debian 13 (Trixie) support
• Docker version alpine-3.18 compatibility
• Enhanced pip installation handling for Debian 12+ with PEP 668 compliance
• docker-compose-plugin support for modern Debian versions
• Fallback mechanism for docker-compose installation from GitHub releases

Changed

• Updated installer to handle Debian 12 and 13 with --break-system-packages pip flag
• Improved docker-compose installation logic for newer Debian versions
• Enhanced version detection and branching logic

Fixed

• pip installation issues on Debian 12+ due to externally-managed-environment restrictions

[Previous] - Earlier Releases

Supported

• Debian 10 (Buster) support
• Debian 11 (Bullseye) support
• Debian 12 (Bookworm) support
• Ubuntu 20.04 support
• Multi-architecture Docker builds (x86_64, armv6/7, aarch64, ppc64)

Features

• Complete HBlink3 server installation via Docker
• HBMonv2 dashboard integration
• Built-in Parrot functionality (configurable)
• Automatic JSON file downloads (RadioID database)
• systemd service management
• Control scripts for easy management:
  • hblink-menu (interactive menu system)
  • hblink-start/stop/restart
  • hblink-update (Docker image updates)
  • hblink-flush (service cleanup)
  • hblink-uninstall (complete removal)
  • hblink-initial-setup (first-time configuration)
  • hblink-upgrade (future upgrades)
• Apache2 web server integration
• Automated cron jobs for log management
• Comprehensive logging to /var/log/hblink

Installation Components

• Docker CE from official Docker repository
• docker-compose or docker-compose-plugin (version-dependent)
• Python 3 with required dependencies
• HBlink3 from https://github.com/ShaYmez/hblink3
• HBMonv2 from https://github.com/ShaYmez/HBMonv2
• Apache2 with PHP support
• systemd service files

Security

• Proper file permissions (755/777) on critical directories
• Container user separation (UID 54000)
• Docker userland-proxy disabled for performance
• Root privilege checks before installation

Documentation

• Comprehensive README.md with installation instructions
• Support for Debian 10, 11, 12, and 13 (Trixie)
• Port forwarding documentation
• Parrot feature configuration guide
• Uninstallation instructions

Repository Information

Upstream Dependencies

• HBlink3: https://github.com/ShaYmez/hblink3
• HBMonv2: https://github.com/ShaYmez/HBMonv2

Compatibility Matrix

Debian Version	Status	Notes
Debian 10 (Buster)	✅ Supported	Uses standard apt packages
Debian 11 (Bullseye)	✅ Supported	Uses standard apt packages
Debian 12 (Bookworm)	✅ Supported	Uses docker-compose-plugin and --break-system-packages
Debian 13 (Trixie)	✅ Supported	Uses docker-compose-plugin and --break-system-packages
Ubuntu 20.04	✅ Supported	Tested and working

Architecture Support

• x86_64 (64-bit Intel/AMD)
• armv6/armv7 (Raspberry Pi and similar)
• aarch64 (ARM 64-bit)
• ppc64 (PowerPC 64-bit)
• Additional architectures via Docker multi-arch support

Maintenance Notes

Known Issues

• None currently reported for Debian 13 support

Upgrade Path

• Users can upgrade from any Debian 10/11/12 installation to Debian 13
• Existing configurations are preserved during system upgrades
• Use hblink-update to pull latest Docker images after OS upgrade

Testing

• All installations should be performed on clean systems
• Destructive installer - not recommended for systems with existing software
• Minimum requirements: 1 core, 512MB RAM, adequate disk space

Contributing

For bugs, features, or support, please visit:

• Main Repository: https://github.com/ShaYmez/hblink3-docker-install
• HBlink3 Repository: https://github.com/ShaYmez/hblink3
• HBMonv2 Repository: https://github.com/ShaYmez/HBMonv2
• Official HBlink3 Upstream: https://github.com/HBLink-org/hblink3

Credits

• Maintainer: Shane Daley - M0VUB (M0VUB)
• Contact: shane@freestar.network
• Dashboard: HBMonv2 by Weldek SP2ONG
• License: GNU General Public License v3.0

---

For detailed installation instructions, see README.md