From f7b63be8e5c57c0f9be1ace588682daa176a6214 Mon Sep 17 00:00:00 2001
From: CanbiZ <47820557+MickLesk@users.noreply.github.com>
Date: Mon, 1 Dec 2025 10:29:48 +0100
Subject: [PATCH] Created [core]: tools.func (markdown)

---
 [core]:-tools.func.md | 1283 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 1283 insertions(+)
 create mode 100644 [core]:-tools.func.md

diff --git a/[core]:-tools.func.md b/[core]:-tools.func.md
new file mode 100644
index 0000000..6a0b537
--- /dev/null
+++ b/[core]:-tools.func.md
@@ -0,0 +1,1283 @@
+# Tools.func Wiki
+
+A comprehensive collection of helper functions for robust package management and repository management in Debian/Ubuntu-based systems.
+
+---
+
+## 📋 Table of Contents
+
+- [Overview](#overview)
+- [Core Helper Functions](#core-helper-functions)
+- [Repository Management](#repository-management)
+- [Package Management](#package-management)
+- [Tool Installation Functions](#tool-installation-functions)
+- [GitHub Integration](#github-integration)
+- [System Utilities](#system-utilities)
+- [Container Setup Functions](#container-setup-functions)
+
+---
+
+## Overview
+
+This function library provides:
+
+- ✅ Automatic retry logic for APT/network failures
+- ✅ Unified keyring cleanup from all 3 locations
+- ✅ Legacy installation cleanup (nvm, rbenv, rustup)
+- ✅ OS-upgrade-safe repository preparation
+- ✅ Service pattern matching for multi-version tools
+
+### Usage in Install Scripts
+
+```bash
+source /dev/stdin <<< "$FUNCTIONS"  # Load from build.func
+prepare_repository_setup "mysql"
+install_packages_with_retry "mysql-server" "mysql-client"
+```
+
+---
+
+## Core Helper Functions
+
+### `cache_installed_version()`
+
+**Purpose**: Caches installed version to avoid repeated checks.
+
+**Parameters**:
+- `$1` - Application name
+- `$2` - Version string
+
+**Example**:
+```bash
+cache_installed_version "nodejs" "22.0.0"
+```
+
+---
+
+### `get_cached_version()`
+
+**Purpose**: Retrieves cached version of an application.
+
+**Parameters**:
+- `$1` - Application name
+
+**Returns**: Version string or empty if not cached
+
+**Example**:
+```bash
+version=$(get_cached_version "nodejs")
+```
+
+---
+
+### `cleanup_tool_keyrings()`
+
+**Purpose**: Removes ALL keyring files for specified tools from all 3 locations.
+
+**Parameters**:
+- `$@` - Tool name patterns (supports wildcards)
+
+**Example**:
+```bash
+cleanup_tool_keyrings "mariadb" "mysql" "postgresql"
+```
+
+---
+
+### `stop_all_services()`
+
+**Purpose**: Stops and disables all service instances matching a pattern.
+
+**Parameters**:
+- `$@` - Service name patterns (supports wildcards)
+
+**Example**:
+```bash
+stop_all_services "php*-fpm" "mysql" "mariadb"
+```
+
+---
+
+### `verify_tool_version()`
+
+**Purpose**: Verifies installed tool version matches expected version.
+
+**Parameters**:
+- `$1` - Tool name
+- `$2` - Expected version
+- `$3` - Installed version
+
+**Returns**: 0 if match, 1 if mismatch
+
+**Example**:
+```bash
+verify_tool_version "nodejs" "22" "$(node -v | grep -oP '^v\K[0-9]+')"
+```
+
+---
+
+### `cleanup_legacy_install()`
+
+**Purpose**: Removes legacy installation methods (nvm, rbenv, rustup, etc.).
+
+**Parameters**:
+- `$1` - Tool name (nodejs, ruby, rust, go)
+
+**Example**:
+```bash
+cleanup_legacy_install "nodejs"  # Removes nvm
+```
+
+---
+
+## Repository Management
+
+### `prepare_repository_setup()`
+
+**Purpose**: Unified repository preparation before setup. Cleans up old repos, keyrings, and ensures APT is working.
+
+**Parameters**:
+- `$@` - Repository names
+
+**Example**:
+```bash
+prepare_repository_setup "mariadb" "mysql"
+```
+
+---
+
+### `manage_tool_repository()`
+
+**Purpose**: Unified repository management for tools. Handles adding, updating, and verifying tool repositories.
+
+**Parameters**:
+- `$1` - Tool name (mariadb, mongodb, nodejs, postgresql, php, mysql)
+- `$2` - Version
+- `$3` - Repository URL
+- `$4` - GPG key URL (optional)
+
+**Supported Tools**: mariadb, mongodb, nodejs, postgresql, php, mysql
+
+**Example**:
+```bash
+manage_tool_repository "mariadb" "11.4" \
+  "http://mirror.mariadb.org/repo/11.4" \
+  "https://mariadb.org/mariadb_release_signing_key.asc"
+```
+
+---
+
+### `setup_deb822_repo()`
+
+**Purpose**: Standardized deb822 repository setup with optional architectures. Always runs apt update after repo creation.
+
+**Parameters**:
+- `$1` - Repository name
+- `$2` - GPG key URL
+- `$3` - Repository URL
+- `$4` - Suite
+- `$5` - Component (default: main)
+- `$6` - Architectures (optional)
+
+**Example**:
+```bash
+setup_deb822_repo "adoptium" \
+  "https://packages.adoptium.net/artifactory/api/gpg/key/public" \
+  "https://packages.adoptium.net/artifactory/deb" \
+  "bookworm" \
+  "main"
+```
+
+---
+
+### `cleanup_old_repo_files()`
+
+**Purpose**: Cleanup old repository files (migration helper for OS upgrades).
+
+**Parameters**:
+- `$1` - Application name
+
+**Example**:
+```bash
+cleanup_old_repo_files "mariadb"
+```
+
+---
+
+### `cleanup_orphaned_sources()`
+
+**Purpose**: Cleanup orphaned .sources files that reference missing keyrings. Prevents APT signature verification errors.
+
+**Example**:
+```bash
+cleanup_orphaned_sources
+```
+
+---
+
+### `ensure_apt_working()`
+
+**Purpose**: Ensures APT is in a working state before installing packages.
+
+**Returns**: 0 if APT is working, 1 if critically broken
+
+**Example**:
+```bash
+ensure_apt_working || return 1
+```
+
+---
+
+### `get_fallback_suite()`
+
+**Purpose**: Get fallback suite for repository with comprehensive mapping.
+
+**Parameters**:
+- `$1` - Distribution ID (debian, ubuntu)
+- `$2` - Distribution codename
+- `$3` - Repository base URL
+
+**Returns**: Appropriate suite name
+
+**Example**:
+```bash
+suite=$(get_fallback_suite "debian" "trixie" "https://repo.example.com")
+```
+
+---
+
+## Package Management
+
+### `install_packages_with_retry()`
+
+**Purpose**: Install packages with retry logic (3 attempts with APT refresh).
+
+**Parameters**:
+- `$@` - Package names
+
+**Example**:
+```bash
+install_packages_with_retry "mysql-server" "mysql-client"
+```
+
+---
+
+### `upgrade_packages_with_retry()`
+
+**Purpose**: Upgrade specific packages with retry logic.
+
+**Parameters**:
+- `$@` - Package names
+
+**Example**:
+```bash
+upgrade_packages_with_retry "mariadb-server" "mariadb-client"
+```
+
+---
+
+### `ensure_dependencies()`
+
+**Purpose**: Ensures dependencies are installed (with apt update caching).
+
+**Parameters**:
+- `$@` - Dependency names
+
+**Example**:
+```bash
+ensure_dependencies "curl" "jq" "git"
+```
+
+---
+
+### `is_package_installed()`
+
+**Purpose**: Check if package is installed (faster than dpkg -l | grep).
+
+**Parameters**:
+- `$1` - Package name
+
+**Returns**: 0 if installed, 1 if not
+
+**Example**:
+```bash
+if is_package_installed "nginx"; then
+  echo "Nginx is installed"
+fi
+```
+
+---
+
+### `hold_package_version()`
+
+**Purpose**: Hold package version to prevent upgrades.
+
+**Parameters**:
+- `$1` - Package name
+
+**Example**:
+```bash
+hold_package_version "mysql-server"
+```
+
+---
+
+### `unhold_package_version()`
+
+**Purpose**: Unhold package version to allow upgrades.
+
+**Parameters**:
+- `$1` - Package name
+
+**Example**:
+```bash
+unhold_package_version "mysql-server"
+```
+
+---
+
+## Tool Installation Functions
+
+### `is_tool_installed()`
+
+**Purpose**: Check if tool is already installed and optionally verify exact version.
+
+**Parameters**:
+- `$1` - Tool name
+- `$2` - Required version (optional)
+
+**Returns**: 0 if installed (with optional version match), 1 if not installed
+
+**Supported Tools**: mariadb, mysql, mongodb, node, php, postgres, ruby, rust, go, clickhouse
+
+**Example**:
+```bash
+is_tool_installed "mariadb" "11.4" || echo "Not installed"
+```
+
+---
+
+### `remove_old_tool_version()`
+
+**Purpose**: Remove old tool version completely (purge + cleanup repos).
+
+**Parameters**:
+- `$1` - Tool name
+- `$2` - Repository name (optional, defaults to tool name)
+
+**Example**:
+```bash
+remove_old_tool_version "mariadb" "repository-name"
+```
+
+---
+
+### `should_update_tool()`
+
+**Purpose**: Determine if tool update/upgrade is needed.
+
+**Parameters**:
+- `$1` - Tool name
+- `$2` - Target version
+
+**Returns**: 0 (update needed), 1 (already up-to-date)
+
+**Example**:
+```bash
+if should_update_tool "mariadb" "11.4"; then
+  echo "Update needed"
+fi
+```
+
+---
+
+### `setup_mariadb()`
+
+**Purpose**: Installs or updates MariaDB from official repo.
+
+**Variables**:
+- `MARIADB_VERSION` - MariaDB version to install (default: latest)
+
+**Example**:
+```bash
+MARIADB_VERSION="11.4" setup_mariadb
+```
+
+---
+
+### `setup_mysql()`
+
+**Purpose**: Installs or upgrades MySQL and configures APT repo.
+
+**Variables**:
+- `MYSQL_VERSION` - MySQL version to install (default: 8.0)
+
+**Features**:
+- Handles Debian Trixie libaio1t64 transition
+- Auto-fallback to MariaDB if MySQL 8.0 unavailable
+
+**Example**:
+```bash
+MYSQL_VERSION="8.0" setup_mysql
+```
+
+---
+
+### `setup_mongodb()`
+
+**Purpose**: Installs or updates MongoDB to specified major version.
+
+**Variables**:
+- `MONGO_VERSION` - MongoDB major version (default: 8.0)
+
+**Example**:
+```bash
+MONGO_VERSION="7.0" setup_mongodb
+```
+
+---
+
+### `setup_postgresql()`
+
+**Purpose**: Installs or upgrades PostgreSQL and optional extensions.
+
+**Variables**:
+- `PG_VERSION` - PostgreSQL major version (default: 16)
+- `PG_MODULES` - Comma-separated list of extensions
+
+**Example**:
+```bash
+PG_VERSION="16" PG_MODULES="postgis,contrib" setup_postgresql
+```
+
+---
+
+### `setup_nodejs()`
+
+**Purpose**: Installs Node.js and optional global modules.
+
+**Variables**:
+- `NODE_VERSION` - Node.js version (default: 22)
+- `NODE_MODULE` - Comma-separated list of global modules
+
+**Example**:
+```bash
+NODE_VERSION="22" NODE_MODULE="yarn,@vue/cli@5.0.0" setup_nodejs
+```
+
+---
+
+### `setup_php()`
+
+**Purpose**: Installs PHP with selected modules and configures Apache/FPM support.
+
+**Variables**:
+- `PHP_VERSION` - PHP version (default: 8.4)
+- `PHP_MODULE` - Additional comma-separated modules
+- `PHP_APACHE` - Set YES to enable PHP with Apache
+- `PHP_FPM` - Set YES to enable PHP-FPM
+- `PHP_MEMORY_LIMIT` - Memory limit (default: 512M)
+- `PHP_UPLOAD_MAX_FILESIZE` - Upload max filesize (default: 128M)
+- `PHP_POST_MAX_SIZE` - Post max size (default: 128M)
+- `PHP_MAX_EXECUTION_TIME` - Max execution time (default: 300)
+
+**Example**:
+```bash
+PHP_VERSION="8.4" PHP_MODULE="redis,imagick" PHP_FPM="YES" setup_php
+```
+
+---
+
+### `setup_java()`
+
+**Purpose**: Installs Temurin JDK via Adoptium APT repository.
+
+**Variables**:
+- `JAVA_VERSION` - Temurin JDK version (default: 21)
+
+**Example**:
+```bash
+JAVA_VERSION="21" setup_java
+```
+
+---
+
+### `setup_ruby()`
+
+**Purpose**: Installs rbenv and ruby-build, installs Ruby and optionally Rails.
+
+**Variables**:
+- `RUBY_VERSION` - Ruby version (default: 3.4.4)
+- `RUBY_INSTALL_RAILS` - true/false to install Rails (default: true)
+
+**Example**:
+```bash
+RUBY_VERSION="3.4.4" RUBY_INSTALL_RAILS="true" setup_ruby
+```
+
+---
+
+### `setup_rust()`
+
+**Purpose**: Installs Rust toolchain and optional global crates.
+
+**Variables**:
+- `RUST_TOOLCHAIN` - Rust toolchain (default: stable)
+- `RUST_CRATES` - Comma-separated list of crates
+
+**Example**:
+```bash
+RUST_TOOLCHAIN="stable" RUST_CRATES="cargo-edit,wasm-pack@0.12.1" setup_rust
+```
+
+---
+
+### `setup_go()`
+
+**Purpose**: Installs Go (Golang) from official tarball.
+
+**Variables**:
+- `GO_VERSION` - Go version (default: latest)
+
+**Example**:
+```bash
+GO_VERSION="1.22.2" setup_go
+```
+
+---
+
+### `setup_composer()`
+
+**Purpose**: Installs or updates Composer globally (robust, idempotent).
+
+**Features**:
+- Installs to /usr/local/bin/composer
+- Removes old binaries/symlinks
+- Ensures /usr/local/bin is in PATH
+- Auto-updates to latest version
+
+**Example**:
+```bash
+setup_composer
+```
+
+---
+
+### `setup_uv()`
+
+**Purpose**: Installs or upgrades uv (Python package manager) from GitHub releases.
+
+**Variables**:
+- `USE_UVX` - Set YES to install uvx wrapper (default: NO)
+- `PYTHON_VERSION` - Optional Python version to install via uv
+
+**Example**:
+```bash
+USE_UVX="YES" PYTHON_VERSION="3.12" setup_uv
+```
+
+---
+
+### `setup_yq()`
+
+**Purpose**: Installs or updates yq (mikefarah/yq - Go version).
+
+**Example**:
+```bash
+setup_yq
+```
+
+---
+
+### `setup_ffmpeg()`
+
+**Purpose**: Installs FFmpeg from source or prebuilt binary.
+
+**Variables**:
+- `FFMPEG_VERSION` - FFmpeg version (default: latest)
+- `FFMPEG_TYPE` - Build profile: minimal, medium, full, binary (default: full)
+
+**Example**:
+```bash
+FFMPEG_VERSION="n7.1.1" FFMPEG_TYPE="full" setup_ffmpeg
+```
+
+---
+
+### `setup_imagemagick()`
+
+**Purpose**: Installs ImageMagick 7 from source.
+
+**Example**:
+```bash
+setup_imagemagick
+```
+
+---
+
+### `setup_gs()`
+
+**Purpose**: Installs or updates Ghostscript (gs) from source.
+
+**Example**:
+```bash
+setup_gs
+```
+
+---
+
+### `setup_hwaccel()`
+
+**Purpose**: Sets up Hardware Acceleration for Intel/AMD/NVIDIA GPUs.
+
+**Example**:
+```bash
+setup_hwaccel
+```
+
+---
+
+### `setup_clickhouse()`
+
+**Purpose**: Installs or upgrades ClickHouse database server.
+
+**Variables**:
+- `CLICKHOUSE_VERSION` - ClickHouse version (default: latest)
+
+**Example**:
+```bash
+CLICKHOUSE_VERSION="latest" setup_clickhouse
+```
+
+---
+
+### `setup_adminer()`
+
+**Purpose**: Installs Adminer (supports Debian/Ubuntu and Alpine).
+
+**Example**:
+```bash
+setup_adminer
+```
+
+---
+
+## GitHub Integration
+
+### `check_for_gh_release()`
+
+**Purpose**: Checks for new GitHub release (latest tag).
+
+**Parameters**:
+- `$1` - Application name
+- `$2` - GitHub repository (user/repo)
+- `$3` - Optional pinned version
+
+**Returns**: 0 if update available, 1 if up-to-date
+
+**Global Variables Set**:
+- `CHECK_UPDATE_RELEASE` - Latest release tag
+
+**Example**:
+```bash
+if check_for_gh_release "flaresolverr" "FlareSolverr/FlareSolverr"; then
+  echo "Update available: $CHECK_UPDATE_RELEASE"
+fi
+```
+
+---
+
+### `fetch_and_deploy_gh_release()`
+
+**Purpose**: Downloads and deploys latest GitHub release.
+
+**Parameters**:
+- `$1` - Application name
+- `$2` - GitHub repository (user/repo)
+- `$3` - Mode: tarball, binary, prebuild, singlefile (default: tarball)
+- `$4` - Version (default: latest)
+- `$5` - Target directory (default: /opt/app)
+- `$6` - Asset filename/pattern (required for prebuild/singlefile)
+
+**Modes**:
+- `tarball` - Source code tarball (.tar.gz)
+- `binary` - .deb package install (arch-dependent)
+- `prebuild` - Prebuilt .tar.gz archive
+- `singlefile` - Standalone binary (chmod +x)
+
+**Example**:
+```bash
+# Source tarball
+fetch_and_deploy_gh_release "myapp" "myuser/myapp"
+
+# Binary .deb
+fetch_and_deploy_gh_release "myapp" "myuser/myapp" "binary"
+
+# Prebuilt archive
+fetch_and_deploy_gh_release "hanko" "teamhanko/hanko" "prebuild" \
+  "latest" "/opt/hanko" "hanko_Linux_x86_64.tar.gz"
+
+# Single binary
+fetch_and_deploy_gh_release "argus" "release-argus/Argus" "singlefile" \
+  "0.26.3" "/opt/argus" "Argus-.*linux-amd64"
+```
+
+---
+
+### `github_api_call()`
+
+**Purpose**: GitHub API call with authentication and rate limit handling.
+
+**Parameters**:
+- `$1` - API URL
+- `$2` - Output file (default: /dev/stdout)
+
+**Environment Variables**:
+- `GITHUB_TOKEN` - Optional GitHub token for higher rate limits
+
+**Example**:
+```bash
+github_api_call "https://api.github.com/repos/user/repo/releases/latest" "/tmp/release.json"
+```
+
+---
+
+### `get_latest_github_release()`
+
+**Purpose**: Get latest GitHub release version.
+
+**Parameters**:
+- `$1` - GitHub repository (user/repo)
+- `$2` - Strip 'v' prefix (default: true)
+
+**Returns**: Version string
+
+**Example**:
+```bash
+version=$(get_latest_github_release "nodejs/node")
+```
+
+---
+
+## System Utilities
+
+### `get_os_info()`
+
+**Purpose**: Get OS information (cached for performance).
+
+**Parameters**:
+- `$1` - Field: id, codename, version, version_id, all (default: all)
+
+**Returns**: Requested OS information
+
+**Example**:
+```bash
+os_id=$(get_os_info id)
+os_codename=$(get_os_info codename)
+```
+
+---
+
+### `is_debian()`, `is_ubuntu()`, `is_alpine()`
+
+**Purpose**: Check if running on specific OS.
+
+**Returns**: 0 if match, 1 if not
+
+**Example**:
+```bash
+if is_debian; then
+  echo "Running on Debian"
+fi
+```
+
+---
+
+### `get_os_version_major()`
+
+**Purpose**: Get Debian/Ubuntu major version.
+
+**Returns**: Major version number
+
+**Example**:
+```bash
+major_version=$(get_os_version_major)
+```
+
+---
+
+### `get_system_arch()`
+
+**Purpose**: Get system architecture (normalized).
+
+**Parameters**:
+- `$1` - Architecture type: dpkg, uname, both (default: both)
+
+**Returns**: Architecture string (amd64, arm64)
+
+**Example**:
+```bash
+arch=$(get_system_arch)
+```
+
+---
+
+### `version_gt()`
+
+**Purpose**: Smart version comparison.
+
+**Parameters**:
+- `$1` - Version 1
+- `$2` - Version 2
+
+**Returns**: 0 if version 1 > version 2
+
+**Example**:
+```bash
+if version_gt "2.0.0" "1.5.0"; then
+  echo "Version 2.0.0 is greater"
+fi
+```
+
+---
+
+### `is_lts_version()`
+
+**Purpose**: Check if running on LTS version.
+
+**Returns**: 0 if LTS, 1 if not
+
+**Example**:
+```bash
+if is_lts_version; then
+  echo "Running on LTS"
+fi
+```
+
+---
+
+### `get_parallel_jobs()`
+
+**Purpose**: Get optimal number of parallel jobs (cached).
+
+**Returns**: Number of parallel jobs based on CPU and memory
+
+**Example**:
+```bash
+jobs=$(get_parallel_jobs)
+make -j"$jobs"
+```
+
+---
+
+### `is_apt_locked()`
+
+**Purpose**: Check if package manager is locked.
+
+**Returns**: 0 if locked, 1 if not
+
+**Example**:
+```bash
+if is_apt_locked; then
+  echo "APT is locked"
+fi
+```
+
+---
+
+### `wait_for_apt()`
+
+**Purpose**: Wait for apt to be available.
+
+**Parameters**:
+- `$1` - Max wait time in seconds (default: 300)
+
+**Example**:
+```bash
+wait_for_apt 600  # Wait up to 10 minutes
+```
+
+---
+
+### `download_file()`
+
+**Purpose**: Download file with retry logic and progress.
+
+**Parameters**:
+- `$1` - URL
+- `$2` - Output path
+- `$3` - Max retries (default: 3)
+- `$4` - Show progress (default: false)
+
+**Example**:
+```bash
+download_file "https://example.com/file.tar.gz" "/tmp/file.tar.gz" 3 true
+```
+
+---
+
+### `create_temp_dir()`
+
+**Purpose**: Create temporary directory with automatic cleanup.
+
+**Returns**: Temporary directory path
+
+**Example**:
+```bash
+tmp_dir=$(create_temp_dir)
+# Directory is automatically cleaned up on exit
+```
+
+---
+
+### `safe_service_restart()`
+
+**Purpose**: Safe service restart with verification.
+
+**Parameters**:
+- `$1` - Service name
+
+**Example**:
+```bash
+safe_service_restart "nginx"
+```
+
+---
+
+### `enable_and_start_service()`
+
+**Purpose**: Enable and start service (with error handling).
+
+**Parameters**:
+- `$1` - Service name
+
+**Example**:
+```bash
+enable_and_start_service "postgresql"
+```
+
+---
+
+### `is_service_enabled()`, `is_service_running()`
+
+**Purpose**: Check if service is enabled/running.
+
+**Parameters**:
+- `$1` - Service name
+
+**Returns**: 0 if yes, 1 if no
+
+**Example**:
+```bash
+if is_service_running "nginx"; then
+  echo "Nginx is running"
+fi
+```
+
+---
+
+### `create_self_signed_cert()`
+
+**Purpose**: Creates and installs self-signed certificates.
+
+**Parameters**:
+- `$1` - Application name (optional, defaults to $APPLICATION)
+
+**Example**:
+```bash
+create_self_signed_cert "myapp"
+```
+
+---
+
+### `import_local_ip()`
+
+**Purpose**: Loads LOCAL_IP from persistent store or detects if missing.
+
+**Global Variables Set**:
+- `LOCAL_IP` - Local IP address
+
+**Example**:
+```bash
+import_local_ip
+echo "Local IP: $LOCAL_IP"
+```
+
+---
+
+### `setup_local_ip_helper()`
+
+**Purpose**: Installs a local IP updater script using networkd-dispatcher.
+
+**Example**:
+```bash
+setup_local_ip_helper
+```
+
+---
+
+### `ensure_usr_local_bin_persist()`
+
+**Purpose**: Ensures /usr/local/bin is permanently in system PATH.
+
+**Example**:
+```bash
+ensure_usr_local_bin_persist
+```
+
+---
+
+### `download_with_progress()`
+
+**Purpose**: Downloads file with optional progress indicator using pv.
+
+**Parameters**:
+- `$1` - URL
+- `$2` - Destination path
+
+**Example**:
+```bash
+download_with_progress "https://example.com/file.tar.gz" "/tmp/file.tar.gz"
+```
+
+---
+
+### `verify_gpg_fingerprint()`
+
+**Purpose**: GPG key fingerprint verification.
+
+**Parameters**:
+- `$1` - Key file path
+- `$2` - Expected fingerprint
+
+**Example**:
+```bash
+verify_gpg_fingerprint "/tmp/key.gpg" "ABCD1234..."
+```
+
+---
+
+### `debug_log()`
+
+**Purpose**: Debug logging (only if DEBUG=1).
+
+**Parameters**:
+- `$@` - Message to log
+
+**Example**:
+```bash
+DEBUG=1 debug_log "This is a debug message"
+```
+
+---
+
+### `start_timer()`, `end_timer()`
+
+**Purpose**: Performance timing helpers.
+
+**Example**:
+```bash
+start_time=$(start_timer)
+# ... do something ...
+end_timer "$start_time" "Operation"
+```
+
+---
+
+## Container Setup Functions
+
+### `color()`
+
+**Purpose**: Sets up color and formatting variables for terminal output.
+
+**Example**:
+```bash
+color
+echo -e "${GN}Success${CL}"
+```
+
+---
+
+### `verb_ip6()`
+
+**Purpose**: Enables or disables IPv6 based on DISABLEIPV6 variable.
+
+**Variables**:
+- `DISABLEIPV6` - Set "yes" to disable IPv6
+
+**Example**:
+```bash
+DISABLEIPV6="yes" verb_ip6
+```
+
+---
+
+### `catch_errors()`
+
+**Purpose**: Sets up error handling for the script.
+
+**Example**:
+```bash
+catch_errors
+```
+
+---
+
+### `error_handler()`
+
+**Purpose**: Handles errors that occur during script execution.
+
+**Parameters**:
+- `$1` - Line number
+- `$2` - Command that failed
+
+**Example**:
+```bash
+error_handler 42 "ls non_existent_file"
+```
+
+---
+
+### `spinner()`
+
+**Purpose**: Displays a rotating spinner animation.
+
+**Example**:
+```bash
+spinner &
+SPINNER_PID=$!
+```
+
+---
+
+### `msg_info()`, `msg_ok()`, `msg_error()`
+
+**Purpose**: Display messages with different statuses.
+
+**Parameters**:
+- `$1` - Message text
+
+**Example**:
+```bash
+msg_info "Installing packages..."
+msg_ok "Installation complete"
+msg_error "Installation failed"
+```
+
+---
+
+### `setting_up_container()`
+
+**Purpose**: Sets up container OS, configures locale, timezone, and network.
+
+**Example**:
+```bash
+setting_up_container
+```
+
+---
+
+### `network_check()`
+
+**Purpose**: Verifies internet connectivity via IPv4 and IPv6.
+
+**Example**:
+```bash
+network_check
+```
+
+---
+
+### `update_os()`
+
+**Purpose**: Updates the container's OS using apt-get.
+
+**Variables**:
+- `CACHER` - Enable package caching proxy
+
+**Example**:
+```bash
+update_os
+```
+
+---
+
+### `motd_ssh()`
+
+**Purpose**: Modifies message of the day (MOTD) and SSH settings.
+
+**Example**:
+```bash
+motd_ssh
+```
+
+---
+
+### `customize()`
+
+**Purpose**: Customizes the container by enabling auto-login and setting up SSH keys.
+
+**Example**:
+```bash
+customize
+```
+
+---
+
+## Best Practices
+
+### Version Management
+
+Always cache versions after installation:
+```bash
+setup_nodejs
+cache_installed_version "nodejs" "$NODE_VERSION"
+```
+
+### Error Handling
+
+Always check return codes:
+```bash
+if ! install_packages_with_retry "nginx"; then
+  msg_error "Failed to install nginx"
+  return 1
+fi
+```
+
+### Repository Setup
+
+Always prepare repositories before installation:
+```bash
+prepare_repository_setup "mariadb" || return 1
+manage_tool_repository "mariadb" "11.4" "$REPO_URL" "$GPG_URL" || return 1
+```
+
+### APT Safety
+
+Always ensure APT is working before operations:
+```bash
+ensure_apt_working || return 1
+install_packages_with_retry "package-name"
+```
+
+---
+
+## Notes
+
+- All functions use `$STD` variable for silent execution
+- Functions support both fresh installs and upgrades
+- Automatic fallback mechanisms for newer OS versions
+- Version caching prevents redundant installations
+- Comprehensive error handling and retry logic
+
+---
+
+## License
+
+This documentation is part of the community-scripts project.
+
+---
+
+## Contributing
+
+Contributions are welcome! Please follow the existing code style and add appropriate documentation for new functions.