tools.func

tools.func – Function Reference

Auto-generated from comments in tools.func. Each entry shows the purpose and usage of the function, where available.

cache_installed_version

Description

• !/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

Usage in install scripts:

get_cached_version

cleanup_tool_keyrings

Description

---

• Clean up ALL keyring locations for a tool (unified helper)

---

Usage / Examples

cleanup_tool_keyrings "mariadb" "mysql" "postgresql"

stop_all_services

Description

---

• Stop and disable all service instances matching a pattern

---

Usage / Examples

stop_all_services "php*-fpm" "mysql" "mariadb"

verify_tool_version

Description

---

• Verify installed tool version matches expected version
• Returns: 0 if match, 1 if mismatch (with warning)

---

Usage / Examples

verify_tool_version "nodejs" "22" "$(node -v | grep -oP '^v\K[0-9]+')"

cleanup_legacy_install

Description

---

• Clean up legacy installation methods (nvm, rbenv, rustup, etc.)

---

Usage / Examples

cleanup_legacy_install "nodejs" -> removes nvm

prepare_repository_setup

Description

---

• Unified repository preparation before setup
• Cleans up old repos, keyrings, and ensures APT is working

---

Usage / Examples

prepare_repository_setup "mariadb" "mysql"

install_packages_with_retry

Description

---

• Install packages with retry logic

---

Usage / Examples

install_packages_with_retry "mysql-server" "mysql-client"

upgrade_packages_with_retry

Description

---

• Upgrade specific packages with retry logic

---

Usage / Examples

upgrade_packages_with_retry "mariadb-server" "mariadb-client"

is_tool_installed

Description

---

• Check if tool is already installed and optionally verify exact version
• Returns: 0 if installed (with optional version match), 1 if not installed

---

Usage / Examples

is_tool_installed "mariadb" "11.4" || echo "Not installed"

remove_old_tool_version

Description

---

• Remove old tool version completely (purge + cleanup repos)

---

Usage / Examples

remove_old_tool_version "mariadb" "repository-name"

should_update_tool

Description

---

• Determine if tool update/upgrade is needed
• Returns: 0 (update needed), 1 (already up-to-date)

---

Usage / Examples

if should_update_tool "mariadb" "11.4"; then ... 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

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

---

• Standardized deb822 repository setup (with optional Architectures)
• Always runs apt update after repo creation to ensure package availability

---

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 (~/.)
• • 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

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 file with optional progress indicator using pv.
• Arguments:
• $1 - URL
• $2 - Destination path

---

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

Description

---

• Downloads and deploys latest GitHub release (source, binary, tarball, asset).
• Description:
• • Fetches latest release metadata from GitHub API
• • Supports the following modes:
• • tarball: Source code tarball (default if omitted)
• • source: Alias for tarball (same behavior)
• • binary: .deb package install (arch-dependent)
• • prebuild: Prebuilt .tar.gz archive (e.g. Go binaries)
• • singlefile: Standalone binary (no archive, direct chmod +x install)
• • Handles download, extraction/installation and version tracking in ~/.
• Parameters:
• $1 APP - Application name (used for install path and version file)
• $2 REPO - GitHub repository in form user/repo
• $3 MODE - Release type:
• tarball → source tarball (.tar.gz)
• binary → .deb file (auto-arch matched)
• prebuild → prebuilt archive (e.g. tar.gz)
• singlefile→ standalone binary (chmod +x)
• $4 VERSION - Optional release tag (default: latest)
• $5 TARGET_DIR - Optional install path (default: /opt/)
• $6 ASSET_FILENAME - Required for:
• • prebuild → archive filename or pattern
• • singlefile→ binary filename or pattern
• Optional:
• • Set GITHUB_TOKEN env var to increase API rate limit (recommended for CI/CD).

• 1. Minimal: Fetch and deploy source tarball

• fetch_and_deploy_gh_release "myapp" "myuser/myapp"

• 2. Binary install via .deb asset (architecture auto-detected)

• fetch_and_deploy_gh_release "myapp" "myuser/myapp" "binary"

• 3. Prebuilt archive (.tar.gz) with asset filename match

• fetch_and_deploy_gh_release "hanko" "teamhanko/hanko" "prebuild" "latest" "/opt/hanko" "hanko_Linux_x86_64.tar.gz"

• 4. Single binary (chmod +x) like Argus, Promtail etc.

• fetch_and_deploy_gh_release "argus" "release-argus/Argus" "singlefile" "0.26.3" "/opt/argus" "Argus-.*linux-amd64"

---

Usage / Examples

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 (Debian/Ubuntu via APT, Alpine via direct download).
• Description:
• • Adds Adminer to Apache or web root
• • Supports Alpine and Debian-based systems

---

setup_composer

Description

---

• Installs or updates Composer globally (robust, idempotent).
• • Installs to /usr/local/bin/composer
• • Removes old binaries/symlinks in /usr/bin, /bin, /root/.composer, etc.
• • Ensures /usr/local/bin is in PATH (permanent)
• • Auto-updates to latest version

---

setup_ffmpeg

Description

---

• Installs FFmpeg from source or prebuilt binary (Debian/Ubuntu only).
• Description:
• • Downloads and builds FFmpeg from GitHub (https://github.com/FFmpeg/FFmpeg)
• • Supports specific version override via FFMPEG_VERSION (e.g. n7.1.1)
• • Supports build profile via FFMPEG_TYPE:
• • minimal : x264, vpx, mp3 only
• • medium : adds subtitles, fonts, opus, vorbis
• • full : adds dav1d, svt-av1, zlib, numa
• • binary : downloads static build (johnvansickle.com)
• • Defaults to latest stable version and full feature set
• Notes:
• • Requires: curl, jq, build-essential, and matching codec libraries
• • Result is installed to /usr/local/bin/ffmpeg

---

setup_go

Description

---

• Installs Go (Golang) from official tarball.
• Description:
• • Determines system architecture
• • Downloads latest version if GO_VERSION not set
• Variables:
• GO_VERSION - Version to install (e.g. 1.22.2 or latest)

---

setup_gs

Description

---

• Installs or updates Ghostscript (gs) from source.
• Description:
• • Fetches latest release
• • Builds and installs system-wide

---

setup_hwaccel

Description

---

• Sets up Hardware Acceleration on debian or ubuntu.
• Description:
• • Determites CPU/GPU/APU Vendor
• • Installs the correct libraries and packages
• • Sets up Hardware Acceleration
• Notes:
• • Some things are fetched from intel repositories due to not being in debian repositories.

---

setup_imagemagick

Description

---

• Installs ImageMagick 7 from source (Debian/Ubuntu only).
• Description:
• • Downloads the latest ImageMagick source tarball
• • Builds and installs ImageMagick to /usr/local
• • Configures dynamic linker (ldconfig)
• Notes:
• • Requires: build-essential, libtool, libjpeg-dev, libpng-dev, etc.

---

setup_java

Description

---

• Installs Temurin JDK via Adoptium APT repository.
• Description:
• • Removes previous JDK if version mismatch
• • Installs or upgrades to specified JAVA_VERSION
• Variables:
• JAVA_VERSION - Temurin JDK version to install (e.g. 17, 21)

---

setup_local_ip_helper

Description

---

• Installs a local IP updater script using networkd-dispatcher.
• Description:
• • Stores current IP in /run/local-ip.env
• • Automatically runs on network changes

---

get_current_ip

setup_mariadb

Description

---

• Installs or updates MariaDB from official repo.
• Description:
• • Detects current MariaDB version and replaces it if necessary
• • Preserves existing database data
• • Dynamically determines latest GA version if "latest" is given
• Variables:
• MARIADB_VERSION - MariaDB version to install (e.g. 10.11, latest) (default: latest)

---

setup_mongodb

Description

---

• Installs or updates MongoDB to specified major version.
• Description:
• • Preserves data across installations
• • Adds official MongoDB repo
• Variables:
• MONGO_VERSION - MongoDB major version to install (e.g. 7.0, 8.0)

---

setup_mysql

Description

---

• Installs or upgrades MySQL and configures APT repo.
• Description:
• • Detects existing MySQL installation
• • Purges conflicting packages before installation
• • Supports clean upgrade
• • Handles Debian Trixie libaio1t64 transition
• Variables:
• MYSQL_VERSION - MySQL version to install (e.g. 5.7, 8.0) (default: 8.0)

---

setup_nodejs

Description

---

• Installs Node.js and optional global modules.
• Description:
• • Installs specified Node.js version using NodeSource APT repo
• • Optionally installs or updates global npm modules
• Variables:
• NODE_VERSION - Node.js version to install (default: 22)
• NODE_MODULE - Comma-separated list of global modules (e.g. "yarn,@vue/cli@5.0.0")

---

setup_php

Description

---

• Installs PHP with selected modules and configures Apache/FPM support.
• Description:
• • Adds Sury PHP repo if needed
• • Installs default and user-defined modules
• • Patches php.ini for CLI, Apache, and FPM as needed
• Variables:
• PHP_VERSION - PHP version to install (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 - (default: 512M)
• PHP_UPLOAD_MAX_FILESIZE - (default: 128M)
• PHP_POST_MAX_SIZE - (default: 128M)
• PHP_MAX_EXECUTION_TIME - (default: 300)

---

setup_postgresql

Description

---

• Installs or upgrades PostgreSQL and optional extensions/modules.
• Description:
• • Detects existing PostgreSQL version
• • Dumps all databases before upgrade
• • Adds PGDG repo and installs specified version
• • Installs optional PG_MODULES (e.g. postgis, contrib)
• • Restores dumped data post-upgrade
• Variables:
• PG_VERSION - Major PostgreSQL version (e.g. 15, 16) (default: 16)

setup_ruby

Description

---

• Installs rbenv and ruby-build, installs Ruby and optionally Rails.
• Description:
• • Downloads rbenv and ruby-build from GitHub
• • Compiles and installs target Ruby version
• • Optionally installs Rails via gem
• Variables:
• RUBY_VERSION - Ruby version to install (default: 3.4.4)
• RUBY_INSTALL_RAILS - true/false to install Rails (default: true)

---

setup_clickhouse

Description

---

• Installs or upgrades ClickHouse database server.
• Description:
• • Adds ClickHouse official repository
• • Installs specified version
• • Configures systemd service
• • Supports Debian/Ubuntu with fallback mechanism
• Variables:
• CLICKHOUSE_VERSION - ClickHouse version to install (default: latest)

---

setup_rust

Description

---

• Installs Rust toolchain and optional global crates via cargo.
• Description:
• • Installs rustup (if missing)
• • Installs or updates desired Rust toolchain (stable, nightly, or versioned)
• • Installs or updates specified global crates using cargo install
• Notes:
• • Skips crate install if exact version is already present
• • Updates crate if newer version or different version is requested
• Variables:
• RUST_TOOLCHAIN - Rust toolchain to install (default: stable)
• RUST_CRATES - Comma-separated list of crates (e.g. "cargo-edit,wasm-pack@0.12.1")

---

setup_uv

Description

---

• Installs or upgrades uv (Python package manager) from GitHub releases.
• • Downloads platform-specific tarball (no install.sh!)
• • Extracts uv binary
• • Places it in /usr/local/bin
• • Optionally installs a specific Python version via uv

---

_install_uvx_wrapper

Description

• Helper function to install uvx wrapper

setup_yq

Description

---

• Installs or updates yq (mikefarah/yq - Go version).
• Description:
• • Checks if yq is installed and from correct source
• • Compares with latest release on GitHub
• • Updates if outdated or wrong implementation

---