From b0b20af5062bd9b518f83c8533282b8628439cb4 Mon Sep 17 00:00:00 2001
From: CanbiZ <47820557+MickLesk@users.noreply.github.com>
Date: Mon, 10 Nov 2025 10:12:08 +0100
Subject: [PATCH] Updated tools.func (markdown)

---
 tools.func.md | 2321 +++++++++++++++++++++++--------------------------
 1 file changed, 1105 insertions(+), 1216 deletions(-)

diff --git a/tools.func.md b/tools.func.md
index 1beef7a..6a0b537 100644
--- a/tools.func.md
+++ b/tools.func.md
@@ -1,1394 +1,1283 @@
-# `tools.func` – Function Reference
+# Tools.func Wiki
 
-_Auto-generated from comments in `tools.func`. Each entry shows the purpose and usage of the function, where available._
+A comprehensive collection of helper functions for robust package management and repository management in Debian/Ubuntu-based systems.
 
+---
 
-## `cache_installed_version`
+## 📋 Table of Contents
 
-**Description**
+- [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)
 
-- !/bin/bash
-- ==============================================================================
-- HELPER FUNCTIONS FOR PACKAGE MANAGEMENT
-- ==============================================================================
-- This file provides unified helper functions for robust package installation
-- and repository management across Debian/Ubuntu OS upgrades.
-- Key Features:
-- - Automatic retry logic for transient 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
-- source /dev/stdin <<< "$FUNCTIONS"  # Load from build.func
-- prepare_repository_setup "mysql"
-- install_packages_with_retry "mysql-server" "mysql-client"
-- Quick Reference (Core Helpers):
-- cleanup_tool_keyrings()          - Remove keyrings from all 3 locations
-- stop_all_services()              - Stop services by pattern (e.g. "php*-fpm")
-- verify_tool_version()            - Validate installed version matches expected
-- cleanup_legacy_install()         - Remove nvm, rbenv, rustup, etc.
-- prepare_repository_setup()       - Cleanup repos + keyrings + validate APT
-- install_packages_with_retry()    - Install with 3 retries and APT refresh
-- upgrade_packages_with_retry()    - Upgrade with 3 retries and APT refresh
-- ==============================================================================
-- ------------------------------------------------------------------------------
-- Cache installed version to avoid repeated checks
-- ------------------------------------------------------------------------------
+---
 
-**Usage / Examples**
+## 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
-Usage in install scripts:
+source /dev/stdin <<< "$FUNCTIONS"  # Load from build.func
+prepare_repository_setup "mysql"
+install_packages_with_retry "mysql-server" "mysql-client"
 ```
 
+---
 
-## `get_cached_version`
+## Core Helper Functions
 
+### `cache_installed_version()`
 
-## `cleanup_tool_keyrings`
+**Purpose**: Caches installed version to avoid repeated checks.
 
-**Description**
+**Parameters**:
+- `$1` - Application name
+- `$2` - Version string
 
-- ------------------------------------------------------------------------------
-- Clean up ALL keyring locations for a tool (unified helper)
-- ------------------------------------------------------------------------------
+**Example**:
+```bash
+cache_installed_version "nodejs" "22.0.0"
+```
 
-**Usage / Examples**
+---
 
+### `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`
+### `stop_all_services()`
 
-**Description**
+**Purpose**: Stops and disables all service instances matching a pattern.
 
-- ------------------------------------------------------------------------------
-- Stop and disable all service instances matching a pattern
-- ------------------------------------------------------------------------------
-
-**Usage / Examples**
+**Parameters**:
+- `$@` - Service name patterns (supports wildcards)
 
+**Example**:
 ```bash
 stop_all_services "php*-fpm" "mysql" "mariadb"
 ```
 
+---
 
-## `verify_tool_version`
+### `verify_tool_version()`
 
-**Description**
+**Purpose**: Verifies installed tool version matches expected version.
 
-- ------------------------------------------------------------------------------
-- Verify installed tool version matches expected version
-- Returns: 0 if match, 1 if mismatch (with warning)
-- ------------------------------------------------------------------------------
+**Parameters**:
+- `$1` - Tool name
+- `$2` - Expected version
+- `$3` - Installed version
 
-**Usage / Examples**
+**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`
+### `cleanup_legacy_install()`
 
-**Description**
+**Purpose**: Removes legacy installation methods (nvm, rbenv, rustup, etc.).
 
-- ------------------------------------------------------------------------------
-- Clean up legacy installation methods (nvm, rbenv, rustup, etc.)
-- ------------------------------------------------------------------------------
-
-**Usage / Examples**
+**Parameters**:
+- `$1` - Tool name (nodejs, ruby, rust, go)
 
+**Example**:
 ```bash
-cleanup_legacy_install "nodejs" -> removes nvm
+cleanup_legacy_install "nodejs"  # Removes nvm
 ```
 
+---
 
-## `prepare_repository_setup`
+## Repository Management
 
-**Description**
+### `prepare_repository_setup()`
 
-- ------------------------------------------------------------------------------
-- Unified repository preparation before setup
-- Cleans up old repos, keyrings, and ensures APT is working
-- ------------------------------------------------------------------------------
+**Purpose**: Unified repository preparation before setup. Cleans up old repos, keyrings, and ensures APT is working.
 
-**Usage / Examples**
+**Parameters**:
+- `$@` - Repository names
 
+**Example**:
 ```bash
 prepare_repository_setup "mariadb" "mysql"
 ```
 
+---
 
-## `install_packages_with_retry`
+### `manage_tool_repository()`
 
-**Description**
+**Purpose**: Unified repository management for tools. Handles adding, updating, and verifying tool repositories.
 
-- ------------------------------------------------------------------------------
-- Install packages with retry logic
-- ------------------------------------------------------------------------------
+**Parameters**:
+- `$1` - Tool name (mariadb, mongodb, nodejs, postgresql, php, mysql)
+- `$2` - Version
+- `$3` - Repository URL
+- `$4` - GPG key URL (optional)
 
-**Usage / Examples**
+**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`
+### `upgrade_packages_with_retry()`
 
-**Description**
+**Purpose**: Upgrade specific packages with retry logic.
 
-- ------------------------------------------------------------------------------
-- Upgrade specific packages with retry logic
-- ------------------------------------------------------------------------------
-
-**Usage / Examples**
+**Parameters**:
+- `$@` - Package names
 
+**Example**:
 ```bash
 upgrade_packages_with_retry "mariadb-server" "mariadb-client"
 ```
 
+---
 
-## `is_tool_installed`
+### `ensure_dependencies()`
 
-**Description**
+**Purpose**: Ensures dependencies are installed (with apt update caching).
 
-- ------------------------------------------------------------------------------
-- Check if tool is already installed and optionally verify exact version
-- Returns: 0 if installed (with optional version match), 1 if not installed
-- ------------------------------------------------------------------------------
+**Parameters**:
+- `$@` - Dependency names
 
-**Usage / Examples**
+**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`
+### `remove_old_tool_version()`
 
-**Description**
+**Purpose**: Remove old tool version completely (purge + cleanup repos).
 
-- ------------------------------------------------------------------------------
-- Remove old tool version completely (purge + cleanup repos)
-- ------------------------------------------------------------------------------
-
-**Usage / Examples**
+**Parameters**:
+- `$1` - Tool name
+- `$2` - Repository name (optional, defaults to tool name)
 
+**Example**:
 ```bash
 remove_old_tool_version "mariadb" "repository-name"
 ```
 
+---
 
-## `should_update_tool`
+### `should_update_tool()`
 
-**Description**
+**Purpose**: Determine if tool update/upgrade is needed.
 
-- ------------------------------------------------------------------------------
-- Determine if tool update/upgrade is needed
-- Returns: 0 (update needed), 1 (already up-to-date)
-- ------------------------------------------------------------------------------
+**Parameters**:
+- `$1` - Tool name
+- `$2` - Target version
 
-**Usage / Examples**
+**Returns**: 0 (update needed), 1 (already up-to-date)
 
+**Example**:
 ```bash
-if should_update_tool "mariadb" "11.4"; then ... fi
+if should_update_tool "mariadb" "11.4"; then
+  echo "Update needed"
+fi
 ```
 
-
-## `manage_tool_repository`
-
-**Description**
-
-- ---------------------–----------------------------------------------------------
-- Unified repository management for tools
-- Handles adding, updating, and verifying tool repositories
-- Supports: mariadb, mongodb, nodejs, postgresql, php, mysql
-- ------------------------------------------------------------------------------
-
-**Usage / Examples**
-
-```bash
-manage_tool_repository "mariadb" "11.4" "https://repo..." "GPG_key_url"
-```
-
-
-## `upgrade_package`
-
-**Description**
-
-- ------–----------------------------------------------------------------------
-- Unified package upgrade function (with apt update caching)
-- ------------------------------------------------------------------------------
-
-
-## `verify_repo_available`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Repository availability check
-- ------------------------------------------------------------------------------
-
-
-## `ensure_dependencies`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Ensure dependencies are installed (with apt update caching)
-- ------------------------------------------------------------------------------
-
-
-## `version_gt`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Smart version comparison
-- ------------------------------------------------------------------------------
-
-
-## `get_system_arch`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Get system architecture (normalized)
-- ------------------------------------------------------------------------------
-
-
-## `create_temp_dir`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Create temporary directory with automatic cleanup
-- ------------------------------------------------------------------------------
-
-
-## `is_package_installed`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Check if package is installed (faster than dpkg -l | grep)
-- ------------------------------------------------------------------------------
-
-
-## `github_api_call`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- GitHub API call with authentication and rate limit handling
-- ------------------------------------------------------------------------------
-
-
-## `should_upgrade`
-
-
-## `get_os_info`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Get OS information (cached for performance)
-- ------------------------------------------------------------------------------
-
-
-## `is_debian`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Check if running on specific OS
-- ------------------------------------------------------------------------------
-
-
-## `is_ubuntu`
-
-
-## `is_alpine`
-
-
-## `get_os_version_major`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Get Debian/Ubuntu major version
-- ------------------------------------------------------------------------------
-
-
-## `download_file`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Download file with retry logic and progress
-- ------------------------------------------------------------------------------
-
-
-## `get_fallback_suite`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Get fallback suite for repository (comprehensive mapping)
-- ------------------------------------------------------------------------------
-
-
-## `verify_package_source`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Verify package source and version
-- ------------------------------------------------------------------------------
-
-
-## `is_lts_version`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Check if running on LTS version
-- ------------------------------------------------------------------------------
-
-
-## `get_parallel_jobs`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Get optimal number of parallel jobs (cached)
-- ------------------------------------------------------------------------------
-
-
-## `get_default_php_version`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Get default PHP version for OS
-- ------------------------------------------------------------------------------
-
-
-## `get_default_python_version`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Get default Python version for OS
-- ------------------------------------------------------------------------------
-
-
-## `get_default_nodejs_version`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Get default Node.js LTS version
-- ------------------------------------------------------------------------------
-
-
-## `is_apt_locked`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Check if package manager is locked
-- ------------------------------------------------------------------------------
-
-
-## `wait_for_apt`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Wait for apt to be available
-- ------------------------------------------------------------------------------
-
-
-## `cleanup_old_repo_files`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Cleanup old repository files (migration helper)
-- ------------------------------------------------------------------------------
-
-
-## `cleanup_orphaned_sources`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Cleanup orphaned .sources files that reference missing keyrings
-- This prevents APT signature verification errors
-- Call this at the start of any setup function to ensure APT is in a clean state
-- ------------------------------------------------------------------------------
-
-
-## `ensure_apt_working`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Ensure APT is in a working state before installing packages
-- This should be called at the start of any setup function
-- ------------------------------------------------------------------------------
-
-
-## `setup_deb822_repo`
-
-### Description
-
-Creates or replaces a **Deb822-style** APT source file for a given repository and associated keyring.
-
-- Cleans up older `.list`, `.sources` and legacy keyring files for the same logical name.
-- Downloads and installs the GPG key into `/etc/apt/keyrings/<name>.gpg`.
-- Writes `/etc/apt/sources.list.d/<name>.sources` with the given URL, suite and components.
-- Optionally sets `Architectures:` if provided.
-- Runs `apt update` afterwards (using `$STD`).
-
-### Arguments
-
-| Position | Name           | Description                                                             |
-|----------|----------------|-------------------------------------------------------------------------|
-| `$1`     | `name`         | Logical repository name (used for filenames and keyring)               |
-| `$2`     | `gpg_url`      | URL to ASCII‑armored or binary GPG key                                 |
-| `$3`     | `repo_url`     | Base APT URL (e.g. `https://repo.homebridge.io`)                       |
-| `$4`     | `suite`        | Suite / codename (e.g. `bookworm`, `noble`, `stable`)                  |
-| `$5`     | `component`    | Component list (default: `main`)                                       |
-| `$6`     | `architectures`| Optional architecture list (e.g. `amd64`, `amd64,arm64`; default: all) |
-
-### Usage
-
-```bash
-# Minimal: single-arch repo for Debian 12 (bookworm)
-setup_deb822_repo   "homebridge"   "https://repo.homebridge.io/KEY.gpg"   "https://repo.homebridge.io"   "stable"   "main"   "amd64"
-
-# Multi-arch: custom tool repo without explicit Architectures line
-setup_deb822_repo   "mytool"   "https://download.example.com/mytool.gpg"   "https://download.example.com/apt"   "bookworm"   "main"
-
-# Using helper get_fallback_suite for unknown distros (inside other functions)
-SUITE=$(get_fallback_suite "$DISTRO_ID" "$DISTRO_CODENAME" "https://repo.mysql.com/apt/${DISTRO_ID}")
-setup_deb822_repo "mysql" "https://repo.mysql.com/RPM-GPG-KEY-mysql-2023"   "https://repo.mysql.com/apt/${DISTRO_ID}" "$SUITE"
-```
-
-
-## `hold_package_version`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Package version hold/unhold helpers
-- ------------------------------------------------------------------------------
-
-
-## `unhold_package_version`
-
-
-## `safe_service_restart`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Safe service restart with verification
-- ------------------------------------------------------------------------------
-
-
-## `enable_and_start_service`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Enable and start service (with error handling)
-- ------------------------------------------------------------------------------
-
-
-## `is_service_enabled`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Check if service is enabled
-- ------------------------------------------------------------------------------
-
-
-## `is_service_running`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Check if service is running
-- ------------------------------------------------------------------------------
-
-
-## `extract_version_from_json`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Extract version from JSON (GitHub releases)
-- ------------------------------------------------------------------------------
-
-
-## `get_latest_github_release`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Get latest GitHub release version
-- ------------------------------------------------------------------------------
-
-
-## `debug_log`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Debug logging (only if DEBUG=1)
-- ------------------------------------------------------------------------------
-
-
-## `start_timer`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Performance timing helper
-- ------------------------------------------------------------------------------
-
-
-## `end_timer`
-
-
-## `verify_gpg_fingerprint`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- GPG key fingerprint verification
-- ------------------------------------------------------------------------------
-
-
-## `check_for_gh_release`
-
-**Description**
-
-- ==============================================================================
-- EXISTING FUNCTIONS
-- ==============================================================================
-- ------------------------------------------------------------------------------
-- Checks for new GitHub release (latest tag).
-- Description:
-- - Queries the GitHub API for the latest release tag
-- - Compares it to a local cached version (~/.<app>)
-- - If newer, sets global CHECK_UPDATE_RELEASE and returns 0
-- if check_for_gh_release "flaresolverr" "FlareSolverr/FlareSolverr" [optional] "v1.1.1"; then
-- # trigger update...
-- fi
-- exit 0
-- } (end of update_script not from the function)
-- Notes:
-- - Requires `jq` (auto-installed if missing)
-- - Does not modify anything, only checks version state
-- - Does not support pre-releases
-- ------------------------------------------------------------------------------
-
-**Usage / Examples**
-
-```bash
-
-```
-
-
-## `create_self_signed_cert`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Creates and installs self-signed certificates.
-- Description:
-- - Create a self-signed certificate with option to override application name
-- Variables:
-- APP   - Application name (default: $APPLICATION variable)
-- ------------------------------------------------------------------------------
-
-
-## `download_with_progress`
-
-### Description
-
-Downloads a file from a URL and shows a progress bar using `pv` when the remote server exposes a `Content-Length` header.
-
-- Automatically installs the `pv` package if missing (via `ensure_dependencies pv`).
-- Integrates with the global spinner: stops any active spinner before drawing progress.
-- Falls back to plain `curl` progress (`-#`) if `Content-Length` is not available.
-- Returns non‑zero on download errors and logs with `msg_error`.
-
-### Arguments
-
-| Position | Name   | Description                |
-|----------|--------|----------------------------|
-| `$1`     | `url`  | Source URL to download     |
-| `$2`     | `path` | Destination file path      |
-
-### Usage
-
-```bash
-# Simple download with progress
-download_with_progress "https://example.com/archive.tar.gz" "/tmp/archive.tar.gz"
-
-# Combined with extraction
-download_with_progress "https://example.com/app.tar.gz" "/tmp/app.tar.gz"   && tar -xzf /tmp/app.tar.gz -C /opt/myapp
-```
-
-
-## `ensure_usr_local_bin_persist`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Ensures /usr/local/bin is permanently in system PATH.
-- Description:
-- - Adds to /etc/profile.d if not present
-- ------------------------------------------------------------------------------
-
-
-## `fetch_and_deploy_gh_release`
-
-Helper to download and deploy GitHub releases in a unified way.  
-It handles API calls, retry logic, asset selection, extraction/installation and simple version caching.
-
-```bash
-fetch_and_deploy_gh_release <app> <repo> [mode] [version] [target] [asset_pattern]
-```
-
-- **`app`** (required)  
-  Logical application name (used for log messages and version cache file at `$HOME/.<app-lowercase-nospace>`).  
-  Can be empty (`""`) if you only want to deploy a library/package without a dedicated app name.
-
-- **`repo`** (required)  
-  GitHub repository in `owner/repository` format, e.g. `paperless-ngx/paperless-ngx`.
-
-- **`mode`** (optional, default: `tarball`)  
-  Controls how the selected release is deployed:
-  - `tarball` / `source` – Download `.tar.gz` source tarball and extract into `target`.
-  - `binary` – Download a `.deb` asset and install it via `apt`/`dpkg`.
-  - `prebuild` – Download a prebuilt archive (`.tar.gz`, `.tgz`, `.zip`) and extract into `target`.
-  - `singlefile` – Download a single binary (or `.jar`) file into `target`.
-
-- **`version`** (optional, default: `latest`)  
-  - `latest` – Uses the latest GitHub release.  
-  - `<tag>` – Uses a specific tag (e.g. `v2.1.0` or `2.1.0`).  
-  The function normalizes leading `v` (so `v2.1.0` → `2.1.0`) and stores the resolved version in the cache file.
-
-- **`target`** (optional, default: `/opt/<app>`)  
-  - For `tarball` and `prebuild`: target directory where the unpacked contents are copied.  
-  - For `binary`: ignored for installation; `.deb` is installed system‑wide via APT/DPKG.  
-  - For `singlefile`: directory where the final file will be placed (`$target/$app` or `$target/$filename`).
-
-- **`asset_pattern`** (optional in general, **required** for `prebuild` and `singlefile`)  
-  Shell filename pattern used to match the asset in the GitHub release, e.g.:
-  - `*-linux-amd64.tar.gz`
-  - `Argus-.*linux-amd64`
-  - `intel-opencl-icd_*_amd64.deb`
-
-  For `binary` mode it is optional; if omitted, the function auto‑selects a `.deb` matching the current architecture and falls back to any `.deb` if needed.
-
 ---
 
-## Behaviour
+### `setup_mariadb()`
 
-- **GitHub API / retries**
-  - Builds `https://api.github.com/repos/<repo>/releases` endpoint, using `/latest` or `/tags/<version>` depending on the `version` argument.
-  - Optional `GITHUB_TOKEN` is respected (adds `Authorization: token ...` header).
-  - Performs a DNS check for the GitHub host and up to 3 retries with short delays if the API call fails.
-  - Fails with a clear error message if the HTTP status is not `200`.
+**Purpose**: Installs or updates MariaDB from official repo.
 
-- **Version caching**
-  - Stores the last successfully deployed version in `$HOME/.<app-lowercase-nospace>`.
-  - If a subsequent call resolves to the same version, it prints a success message and returns early without downloading/installing again.
-
-- **CLEAN_INSTALL support**
-  - If `CLEAN_INSTALL=1`, the target directory is removed (`rm -rf "$target/*"`) before copying new contents in `tarball` and `prebuild` modes.
-  - This is useful when you want a clean deployment without leftover files.
-
-- **Mode details**
-
-  ### `tarball` / `source`
-  - Uses `.tarball_url` from the GitHub release; if missing, falls back to  
-    `https://github.com/<repo>/archive/refs/tags/v<version>.tar.gz`.
-  - Downloads `<app-lc>-<version>.tar.gz` into a temporary directory.
-  - Extracts the tarball and copies the contents of the top‑level folder into `target`.
-
-  ### `binary`
-  - Collects all `.assets[].browser_download_url` values from the release.
-  - If `asset_pattern` is provided, selects the first asset whose file name matches the shell pattern.
-  - Otherwise, auto‑detects the current architecture (`dpkg --print-architecture` / `uname -m`) and prefers `.deb` files that contain `amd64`, `arm64`, etc.
-  - If no architecture match is found, falls back to any `.deb` asset.
-  - Downloads the `.deb` into a temporary directory and installs it using:
-    - `apt install -y /path/to/file.deb`
-    - If `apt` fails, falls back to `dpkg -i /path/to/file.deb`.
-
-  ### `prebuild`
-  - **Requires** `asset_pattern`.  
-  - Selects an asset whose file name matches `asset_pattern`.
-  - Downloads the archive (`.tar.gz`, `.tgz`, `.zip`) to a temporary directory and unpacks it into another temporary directory.
-  - If there is exactly one top‑level directory, that inner directory is “stripped” and its contents are copied into `target`.  
-    Otherwise, all contents of the unpack directory are copied.
-  - Respects `CLEAN_INSTALL=1` to wipe `target` before copying.
-
-  ### `singlefile`
-  - **Requires** `asset_pattern`.  
-  - Selects an asset whose file name matches `asset_pattern`.
-  - Downloads the file directly into `target` and uses:
-    - Default file name: `<app>`
-    - If `USE_ORIGINAL_FILENAME=true`, uses the original asset file name instead.
-  - If the resulting file does **not** end with `.jar`, it is marked executable (`chmod +x`).
-
-- **Cleanup**
-  - All temporary directories are removed at the end.
-  - The resolved `version` is written back into the cache file.  
-
-If any error occurs (API failure, missing asset, extraction failure, etc.), the function prints an error message via `msg_error`, cleans up temporary resources, and returns with a non‑zero exit code.
-
----
-
-## Examples
-
-### Basic usage with defaults (tarball mode, latest version)
+**Variables**:
+- `MARIADB_VERSION` - MariaDB version to install (default: latest)
 
+**Example**:
 ```bash
-# Fetch latest release as source tarball and extract into /opt/MyApp
-fetch_and_deploy_gh_release "MyApp" "owner/repository"
-```
-
-### Install latest `.deb` as binary
-
-```bash
-# Auto‑detect architecture and pick the matching .deb
-fetch_and_deploy_gh_release "MyApp" "owner/repository" "binary"
-```
-
-### Install specific version as `.deb` package with filename pattern
-
-```bash
-# Install v2.1.0 using a specific .deb asset
-fetch_and_deploy_gh_release "MyApp" "owner/repository" "binary" "v2.1.0" "" "*_linux_amd64.deb"
-```
-
-### Install prebuilt archive with custom target and asset pattern
-
-```bash
-# Download and unpack a prebuilt archive into /usr/local/myapp
-fetch_and_deploy_gh_release "MyApp" "owner/repository" "prebuild" "latest" "/usr/local/myapp" "*-linux-amd64.tar.gz"
-```
-
-### Deploy a single binary (Argus example)
-
-```bash
-fetch_and_deploy_gh_release "Argus" "release-argus/Argus" "singlefile" "0.26.3" "/opt/argus" "Argus-.*linux-amd64"
-```
-
-### Use without app name for helper libraries
-
-```bash
-# Example for Intel GPU runtime .deb, app name left empty on purpose
-fetch_and_deploy_gh_release "" "intel/compute-runtime" "binary" "latest" "" "intel-opencl-icd_*_amd64.deb"
-```
-
-
-## `import_local_ip`
-
-**Description**
-
-- ------------------------------------------------------------------------------
-- Loads LOCAL_IP from persistent store or detects if missing.
-- Description:
-- - Loads from /run/local-ip.env or performs runtime lookup
-- ------------------------------------------------------------------------------
-
-
-## `get_current_ip`
-
-
-## `setup_adminer`
-
-### Description
-
-Installs **Adminer** (lightweight database management UI) as a PHP application.
-
-- Downloads the latest Adminer PHP file into `/var/www/adminer` (or similar path used by the script).
-- Ensures required PHP and webserver components are available (via other helpers like `setup_php`).
-- Can be reused by multiple scripts that want to deploy Adminer quickly for DB access.
-
-> Exact paths and vhost integration are controlled by the calling `*-install.sh` script.
-
-### Usage
-
-```bash
-# Install Adminer into the standard location
-setup_adminer
-
-# After installation, point your webserver (nginx/apache) to the Adminer PHP file.
-```
-
-
-## `setup_composer`
-
-### Description
-
-Installs or updates **Composer** globally in a robust, idempotent way.
-
-- Installs Composer to `/usr/local/bin/composer` using the official installer.
-- Removes old Composer binaries/symlinks from `/usr/bin`, `/bin`, `$HOME/.composer`, etc.
-- Ensures `/usr/local/bin` is in `$PATH` (persistent shell profile update).
-- Always allows running as root (`COMPOSER_ALLOW_SUPERUSER=1`).
-- Runs `composer self-update` to make sure the binary is at the latest stable version.
-
-### Usage
-
-```bash
-# Install or update Composer globally
-setup_composer
-
-# Check installed version
-composer --version
-```
-
-
-## `setup_ffmpeg`
-
-### Description
-
-Builds or installs **FFmpeg** with configurable feature set.
-
-- Downloads FFmpeg sources from the official GitHub repo.
-- Supports different build profiles via `FFMPEG_TYPE`:
-  - `minimal` – x264, vpx, mp3 only.
-  - `medium`  – adds subtitles, fonts, opus, vorbis.
-  - `full`    – adds dav1d, svt-av1, zlib, numa (default).
-  - `binary`  – downloads a static build from `johnvansickle.com` instead of building.
-- Installs resulting `ffmpeg` binary into `/usr/local/bin/ffmpeg`.
-
-### User-Configurable Variables
-
-| Variable          | Description                                                        | Default  |
-|-------------------|--------------------------------------------------------------------|----------|
-| `FFMPEG_VERSION`  | FFmpeg version tag (e.g. `n7.1.1`, `latest`).                      | `latest` |
-| `FFMPEG_TYPE`     | Build profile: `minimal`, `medium`, `full`, `binary`.             | `full`   |
-
-### Usage
-
-```bash
-# Install latest FFmpeg with full feature set
-setup_ffmpeg
-
-# Build a specific version with minimal codecs
-FFMPEG_VERSION="n7.1.1" FFMPEG_TYPE="minimal" setup_ffmpeg
-
-# Use a prebuilt static binary instead of compiling
-FFMPEG_TYPE="binary" setup_ffmpeg
-```
-
-
-## `setup_go`
-
-### Description
-
-Installs or upgrades **Go (Golang)** from the official tarball distribution.
-
-- Detects CPU architecture (`amd64` / `arm64`) and selects matching tarball.
-- If `GO_VERSION=latest`, queries `https://go.dev/VERSION?m=text` for the latest tag.
-- Removes any existing `/usr/local/go` tree when versions differ.
-- Extracts Go to `/usr/local/go` and ensures `go` is available in `/usr/local/bin`.
-- Suitable for Debian/Ubuntu; does not rely on distro packages.
-
-### User-Configurable Variables
-
-| Variable     | Description                                             | Default  |
-|--------------|---------------------------------------------------------|----------|
-| `GO_VERSION` | Go version to install (e.g. `1.22.4`, `1.21.11`, `latest`). | `latest` |
-
-### Usage
-
-```bash
-# Install latest Go
-setup_go
-
-# Install a specific Go version
-GO_VERSION="1.22.4" setup_go
-```
-
-
-## `setup_gs`
-
-### Description
-
-Builds and installs the latest **Ghostscript (gs)** from source.
-
-- Queries GitHub releases for `ghostpdl-downloads` to determine the latest Ghostscript version.
-- If already up to date, caches version and returns without rebuilding.
-- Downloads the source tarball, configures, compiles and installs it system‑wide.
-- Runs `ldconfig` to register shared libraries.
-- If the GitHub API is not reachable but `gs` is already installed, reuses the current version and exits cleanly.
-
-### Usage
-
-```bash
-# Install or update Ghostscript
-setup_gs
-
-# Verify installation
-gs --version
-```
-
-
-## `setup_hwaccel`
-
-### Description
-
-Configures **hardware acceleration** libraries (Intel/AMD/NVIDIA) on Debian/Ubuntu.
-
-- Ensures `pciutils` (`lspci`) is installed to detect GPU vendor.
-- Detects GPU vendor (Intel, AMD, NVIDIA) from `lspci` output.
-- Installs appropriate VAAPI / NVENC / AMD GPU libraries and drivers from distro and vendor repos.
-- Optionally pulls Intel GPU runtime components from Intel repositories when not available in Debian.
-
-> This helper is intended as a one‑shot setup for media workloads (e.g. FFmpeg, Jellyfin, Frigate).
-
-### Usage
-
-```bash
-# Auto-detect hardware and install appropriate acceleration stack
-setup_hwaccel
-```
-
-
-## `setup_imagemagick`
-
-### Description
-
-Builds and installs **ImageMagick 7** from source.
-
-- Downloads the latest ImageMagick source tarball.
-- Compiles and installs to `/usr/local`.
-- Runs `ldconfig` to refresh the dynamic linker cache.
-- Requires common image‑related development libraries (`libjpeg-dev`, `libpng-dev`, etc.).
-
-### Usage
-
-```bash
-# Install or update ImageMagick 7
-setup_imagemagick
-
-# Verify
-magick -version
-```
-
-
-## `setup_java`
-
-### Description
-
-Installs or upgrades **Temurin JDK** from the Adoptium repository.
-
-- Detects distro ID/codename and configures `adoptium.sources` via `setup_deb822_repo`.
-- Removes any previously installed Temurin JDK if the version differs.
-- Installs `temurin-<JAVA_VERSION>-jdk` via APT.
-- Caches the installed version for future checks.
-
-### User-Configurable Variables
-
-| Variable       | Description                                     | Default |
-|----------------|-------------------------------------------------|---------|
-| `JAVA_VERSION` | Temurin JDK major version (e.g. `17`, `21`).    | `21`    |
-
-### Usage
-
-```bash
-# Install default JDK 21
-setup_java
-
-# Install JDK 17
-JAVA_VERSION=17 setup_java
-```
-
-
-## `setup_local_ip_helper`
-
-### Description
-
-Installs a **local IP helper** using `networkd-dispatcher` to keep the current IP in `/run/local-ip.env`.
-
-- Creates `/usr/local/community-scripts/ip-management/update_local_ip.sh` with logic to detect current IP.
-- Installs a `networkd-dispatcher` hook (`/usr/lib/networkd-dispatcher/routable.d/50-local-ip-update`) that runs on network changes.
-- Writes `LOCAL_IP=<ip>` into `/run/local-ip.env` whenever the IP changes.
-- Uses `cache_installed_version` to track helper version (`local-ip-helper`).
-
-### Usage
-
-```bash
-# One-time setup inside a Debian/Ubuntu container/VM
-setup_local_ip_helper
-
-# Later in other scripts, import the IP
-import_local_ip
-echo "Current IP is: $LOCAL_IP"
-```
-
-
-## `setup_mariadb`
-
-### Description
-
-Installs or upgrades **MariaDB** using the official MariaDB APT repositories.
-
-- Resolves `MARIADB_VERSION=latest` to the latest GA version via `mirror.mariadb.org`.
-- Detects currently installed MariaDB version (`mysql --version`).
-- If the same version is installed, only refreshes packages (`apt update` + upgrade).
-- If a different version is installed, configures new repo, removes old server packages, and installs the requested version.
-- Uses `manage_tool_repository` to configure `mariadb.sources` safely across distros.
-
-### User-Configurable Variables
-
-| Variable          | Description                                                                   | Default  |
-|-------------------|-------------------------------------------------------------------------------|----------|
-| `MARIADB_VERSION` | Target MariaDB version (e.g. `10.11`, `11.4`, `12.0`, or `latest`).           | `latest` |
-
-### Usage
-
-```bash
-# Install latest GA MariaDB version
-setup_mariadb
-
-# Install a fixed MariaDB minor version
 MARIADB_VERSION="11.4" setup_mariadb
-
-# Pin to 12.0 even when "latest" would move forward later
-MARIADB_VERSION="12.0" setup_mariadb
 ```
 
+---
 
-## `setup_mongodb`
+### `setup_mysql()`
 
-### Description
+**Purpose**: Installs or upgrades MySQL and configures APT repo.
 
-Installs or upgrades **MongoDB** from the official MongoDB repository.
+**Variables**:
+- `MYSQL_VERSION` - MySQL version to install (default: 8.0)
 
-- Detects distro (`debian`/`ubuntu`) and configures the appropriate MongoDB APT repo.
-- Preserves existing data directories; only packages are upgraded/installed.
-- Verifies AVX support for newer MongoDB versions and fails early if unsupported.
-- Installs `mongodb-org` for the requested `MONGO_VERSION`.
-- Enables and starts the MongoDB systemd service.
-
-### User-Configurable Variables
-
-| Variable        | Description                                        | Default |
-|-----------------|----------------------------------------------------|---------|
-| `MONGO_VERSION` | MongoDB major version (e.g. `6.0`, `7.0`, `8.0`).  | `8.0`   |
-
-### Usage
+**Features**:
+- Handles Debian Trixie libaio1t64 transition
+- Auto-fallback to MariaDB if MySQL 8.0 unavailable
 
+**Example**:
 ```bash
-# Install default MongoDB 8.0
-setup_mongodb
+MYSQL_VERSION="8.0" setup_mysql
+```
 
-# Install MongoDB 7.0 (e.g. on older CPUs without AVX2)
+---
+
+### `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_mysql`
+### `setup_postgresql()`
 
-### Description
+**Purpose**: Installs or upgrades PostgreSQL and optional extensions.
 
-Installs or upgrades **MySQL Server** using the official MySQL APT repository.
-
-- Detects currently installed MySQL version and compares with `MYSQL_VERSION`.
-- For Debian 13+ (`trixie`, `forky`, `sid`), automatically normalizes `8.0` to `8.4` due to `libaio1t64` issues.
-- Uses `manage_tool_repository` to configure `mysql.sources` safely.
-- Tries multiple package names (`mysql-server`, `mysql-community-server`, etc.) with retries to handle distro differences.
-- Verifies that the `mysql` client command is present after installation.
-
-### User-Configurable Variables
-
-| Variable        | Description                                        | Default |
-|-----------------|----------------------------------------------------|---------|
-| `MYSQL_VERSION` | MySQL major version to install (e.g. `8.0`, `8.4`).| `8.0`   |
-
-### Usage
+**Variables**:
+- `PG_VERSION` - PostgreSQL major version (default: 16)
+- `PG_MODULES` - Comma-separated list of extensions
 
+**Example**:
 ```bash
-# Install default MySQL 8.0 (or auto-switch to 8.4 on Debian 13+)
-setup_mysql
-
-# Explicitly install MySQL 8.4 LTS
-MYSQL_VERSION="8.4" setup_mysql
+PG_VERSION="16" PG_MODULES="postgis,contrib" setup_postgresql
 ```
 
+---
 
-## `setup_nodejs`
+### `setup_nodejs()`
 
-### Description
+**Purpose**: Installs Node.js and optional global modules.
 
-Installs or upgrades **Node.js** from the official NodeSource APT repository and optionally installs global npm modules.
-
-- Detects an existing Node.js installation and replaces it if the major version differs.
-- Configures NodeSource deb822 repo (`nodesource.sources`) using `manage_tool_repository`.
-- Updates Node.js packages using `install_packages_with_retry` / `upgrade_packages_with_retry`.
-- Optionally installs or updates a comma‑separated list of global npm modules.
-- Sets sane defaults for `NODE_OPTIONS` (e.g. `--max-old-space-size=4096`) to avoid memory issues.
-
-### User-Configurable Variables
-
-| Variable       | Description                                                                                 | Default |
-|----------------|---------------------------------------------------------------------------------------------|---------|
-| `NODE_VERSION` | Node.js major version to install (e.g. `20`, `22`).                                         | `22`    |
-| `NODE_MODULE`  | Comma‑separated list of global npm modules, optionally with versions (e.g. `yarn,@vue/cli@5.0.0`). | *(empty)* |
-
-### Usage
+**Variables**:
+- `NODE_VERSION` - Node.js version (default: 22)
+- `NODE_MODULE` - Comma-separated list of global modules
 
+**Example**:
 ```bash
-# Install default Node.js (22.x) without global modules
-setup_nodejs
-
-# Install Node.js 20.x and yarn globally
-NODE_VERSION=20 NODE_MODULE="yarn" setup_nodejs
-
-# Install Node.js 22.x and several global CLIs
-NODE_VERSION=22 NODE_MODULE="yarn,@vue/cli-service@5.0.0,typescript" setup_nodejs
+NODE_VERSION="22" NODE_MODULE="yarn,@vue/cli@5.0.0" setup_nodejs
 ```
 
+---
 
-## `setup_php`
+### `setup_php()`
 
-### Description
+**Purpose**: Installs PHP with selected modules and configures Apache/FPM support.
 
-Installs or upgrades **PHP** from the `sury.org` repository, including common modules and optional Apache/PHP‑FPM integration.
-
-- Detects current PHP major.minor version and decides between fresh install or upgrade.
-- Ensures `php.sources` from Sury is present via `manage_tool_repository`.
-- Installs a base set of common modules plus any extra modules from `PHP_MODULE`.
-- Patches relevant `php.ini` files with custom memory/upload limits and timeouts.
-- Optionally enables Apache PHP module and/or PHP‑FPM service and restarts them safely.
-
-### User-Configurable Variables
-
-| Variable                  | Description                                                              | Default |
-|---------------------------|--------------------------------------------------------------------------|---------|
-| `PHP_VERSION`             | PHP version to install (e.g. `8.2`, `8.3`, `8.4`).                       | `8.4`   |
-| `PHP_MODULE`              | Comma‑separated list of extra modules (e.g. `mysql,redis,imagick`).     | *(empty)* |
-| `PHP_APACHE`              | `YES` to enable Apache `libapache2-mod-php` for this PHP version.       | `NO`    |
-| `PHP_FPM`                 | `YES` to install and enable `php<ver>-fpm` systemd service.             | `NO`    |
-| `PHP_MEMORY_LIMIT`        | `memory_limit` setting in `php.ini`.                                    | `512M`  |
-| `PHP_UPLOAD_MAX_FILESIZE` | `upload_max_filesize` in `php.ini`.                                     | `128M`  |
-| `PHP_POST_MAX_SIZE`       | `post_max_size` in `php.ini`.                                           | `128M`  |
-| `PHP_MAX_EXECUTION_TIME`  | `max_execution_time` in `php.ini`.                                      | `300`   |
-
-Default modules installed include: `bcmath, cli, curl, gd, intl, mbstring, opcache, readline, xml, zip`.
-
-### Usage
+**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
-# Install default PHP 8.4 with standard modules
-setup_php
-
-# Install PHP 8.3 with Apache module and FPM
-PHP_VERSION="8.3" PHP_APACHE="YES" PHP_FPM="YES" setup_php
-
-# Install PHP 8.2 with extra modules and custom limits
-PHP_VERSION="8.2" PHP_MODULE="mysql,redis,imagick" PHP_MEMORY_LIMIT="1G" PHP_UPLOAD_MAX_FILESIZE="512M" PHP_POST_MAX_SIZE="512M" PHP_MAX_EXECUTION_TIME="600" setup_php
+PHP_VERSION="8.4" PHP_MODULE="redis,imagick" PHP_FPM="YES" setup_php
 ```
 
+---
 
-## `setup_postgresql`
+### `setup_java()`
 
-### Description
+**Purpose**: Installs Temurin JDK via Adoptium APT repository.
 
-Installs or upgrades **PostgreSQL** from the official PGDG repository and optionally enables extensions/modules.
-
-- Detects currently installed PostgreSQL major version (via `psql --version`).
-- Before a major upgrade, dumps all databases with `pg_dumpall` into `/var/lib/postgresql/backup_<date>_v<old>.sql`.
-- Configures the `apt.postgresql.org` repository via `manage_tool_repository`.
-- Installs or upgrades the target `postgresql-<PG_VERSION>` packages.
-- Optionally installs additional `postgresql-<PG_VERSION>-<module>` packages from `PG_MODULES`.
-- After upgrade, restores the dump (best-effort) and logs failures with `msg_warn`.
-
-### User-Configurable Variables
-
-| Variable      | Description                                                       | Default |
-|---------------|-------------------------------------------------------------------|---------|
-| `PG_VERSION`  | Target PostgreSQL major version (e.g. `15`, `16`).                | `16`    |
-| `PG_MODULES`  | Comma‑separated list of extra modules (e.g. `postgis,contrib`).   | *(empty)* |
-
-### Usage
+**Variables**:
+- `JAVA_VERSION` - Temurin JDK version (default: 21)
 
+**Example**:
 ```bash
-# Install default PostgreSQL 16
-setup_postgresql
-
-# Install PostgreSQL 15
-PG_VERSION=15 setup_postgresql
-
-# Install PostgreSQL 16 with PostGIS and contrib modules
-PG_VERSION=16 PG_MODULES="postgis,contrib" setup_postgresql
+JAVA_VERSION="21" setup_java
 ```
 
+---
 
-## `setup_ruby`
+### `setup_ruby()`
 
-### Description
+**Purpose**: Installs rbenv and ruby-build, installs Ruby and optionally Rails.
 
-Installs or upgrades **Ruby** via `rbenv` and `ruby-build`.
-
-- Installs `rbenv` and `ruby-build` into `$HOME/.rbenv` if missing.
-- Adds the required `eval "$(rbenv init - bash)"` line to `~/.profile`.
-- Installs the requested Ruby version and sets it as global default.
-- Optionally installs the latest `rails` gem when `RUBY_INSTALL_RAILS=true`.
-- Caches the installed Ruby version for future checks.
-
-### User-Configurable Variables
-
-| Variable             | Description                                      | Default  |
-|----------------------|--------------------------------------------------|----------|
-| `RUBY_VERSION`       | Ruby version to install (e.g. `3.3.2`, `3.4.4`). | `3.4.4`  |
-| `RUBY_INSTALL_RAILS` | Whether to install the `rails` gem (`true/false`).| `true`   |
-
-### Usage
+**Variables**:
+- `RUBY_VERSION` - Ruby version (default: 3.4.4)
+- `RUBY_INSTALL_RAILS` - true/false to install Rails (default: true)
 
+**Example**:
 ```bash
-# Install Ruby 3.4.4 and Rails
-setup_ruby
-
-# Install Ruby 3.3.2 without Rails
-RUBY_VERSION="3.3.2" RUBY_INSTALL_RAILS=false setup_ruby
+RUBY_VERSION="3.4.4" RUBY_INSTALL_RAILS="true" setup_ruby
 ```
 
+---
 
-## `setup_clickhouse`
+### `setup_rust()`
 
-### Description
+**Purpose**: Installs Rust toolchain and optional global crates.
 
-Installs or upgrades **ClickHouse** using the official repositories.
-
-- Detects distro ID/codename and sets up ClickHouse `deb` repositories.
-- Resolves `CLICKHOUSE_VERSION=latest` from package index or fallback GitHub API.
-- Installs or upgrades `clickhouse-server` and related packages for the target version.
-- Enables and starts the ClickHouse systemd service.
-
-### User-Configurable Variables
-
-| Variable             | Description                                       | Default  |
-|----------------------|---------------------------------------------------|----------|
-| `CLICKHOUSE_VERSION` | ClickHouse version (e.g. `24.3.2.20`, or `latest`).| `latest` |
-
-### Usage
+**Variables**:
+- `RUST_TOOLCHAIN` - Rust toolchain (default: stable)
+- `RUST_CRATES` - Comma-separated list of crates
 
+**Example**:
 ```bash
-# Install latest ClickHouse
-setup_clickhouse
-
-# Install a specific ClickHouse version
-CLICKHOUSE_VERSION="24.3.2.20" setup_clickhouse
+RUST_TOOLCHAIN="stable" RUST_CRATES="cargo-edit,wasm-pack@0.12.1" setup_rust
 ```
 
+---
 
-## `setup_rust`
+### `setup_go()`
 
-### Description
+**Purpose**: Installs Go (Golang) from official tarball.
 
-Installs or upgrades the **Rust toolchain** via `rustup` and optionally ensures a set of global cargo crates.
-
-- Installs `rustup` if missing and configures `$HOME/.cargo/bin` in the PATH.
-- Ensures the requested toolchain (e.g. `stable`, `nightly`, `1.78.0`) is installed.
-- Optionally installs or updates specified crates:
-  - Skips if the exact version is already present.
-  - Updates if a different or newer version is requested.
-
-### User-Configurable Variables
-
-| Variable         | Description                                                                 | Default  |
-|------------------|-----------------------------------------------------------------------------|----------|
-| `RUST_TOOLCHAIN` | Rust toolchain to install (e.g. `stable`, `nightly`, `1.78.0`).            | `stable` |
-| `RUST_CRATES`    | Comma‑separated crates, optionally with versions (e.g. `cargo-edit,wasm-pack@0.12.1`). | *(empty)* |
-
-### Usage
+**Variables**:
+- `GO_VERSION` - Go version (default: latest)
 
+**Example**:
 ```bash
-# Install stable Rust
-setup_rust
-
-# Install nightly Rust with some global tools
-RUST_TOOLCHAIN="nightly" RUST_CRATES="cargo-edit,wasm-pack@0.12.1" setup_rust
+GO_VERSION="1.22.2" setup_go
 ```
 
+---
 
-## `setup_uv`
+### `setup_composer()`
 
-### Description
+**Purpose**: Installs or updates Composer globally (robust, idempotent).
 
-Installs or upgrades **uv** (Astral's Python package manager) from GitHub releases.
-
-- Detects architecture (`x86_64`, `aarch64`, etc.) and libc (`gnu` vs `musl` for Alpine) to pick the correct tarball.
-- Downloads and extracts the `uv` binary directly (no `install.sh`).
-- Places `uv` and `uvx` into `/usr/local/bin` and ensures the directory persists across container restarts.
-- Caches the installed version and skips reinstall if already up to date.
-- Optionally installs a specific Python version with `uv python install` when `PYTHON_VERSION` is set.
-
-### User-Configurable Variables
-
-| Variable         | Description                                            | Default |
-|------------------|--------------------------------------------------------|---------|
-| `PYTHON_VERSION` | Optional Python version to install via `uv python`.    | *(unset)* |
-
-### Usage
+**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
-# Install or update uv
-setup_uv
-
-# Install uv and also provision Python 3.12
-PYTHON_VERSION="3.12" setup_uv
-
-# After installation, use uv as usual
-uv venv .venv
-uv pip install -r requirements.txt
+setup_composer
 ```
 
+---
 
-## `_install_uvx_wrapper`
+### `setup_uv()`
 
-**Description**
+**Purpose**: Installs or upgrades uv (Python package manager) from GitHub releases.
 
-- Helper function to install uvx wrapper
-
-
-## `setup_yq`
-
-### Description
-
-Installs or updates the Go‑based **yq** from `mikefarah/yq` GitHub releases.
-
-- Ensures that any existing `yq` binary comes from `mikefarah` (removes incompatible variants).
-- Fetches latest release metadata from the GitHub API.
-- Downloads the correct binary for the current architecture and installs it to `/usr/local/bin/yq`.
-- Ensures `/usr/local/bin` is on the PATH and persisted.
-
-### Usage
+**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
-# Install or update yq
 setup_yq
-
-# Example usage in scripts
-yq '.services[].name' docker-compose.yml
 ```
+
+---
+
+### `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.