Skip to content

tools.func

Jump to bottom
CanbiZ edited this page Nov 10, 2025 · 16 revisions

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

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

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


# 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.


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


    

  • 

    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.
      • 

    

    • 

  • 

    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)


# Fetch latest release as source tarball and extract into /opt/MyApp
fetch_and_deploy_gh_release "MyApp" "owner/repository"


Install latest .deb as binary


# 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


# 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


# 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)


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


# 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


# 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


# 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


# 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


# 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


# 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


# 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


# 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


# 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


# 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


# 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


Description


Installs or upgrades MongoDB from the official MongoDB repository.


    

  • 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


# Install default MongoDB 8.0
setup_mongodb

# Install MongoDB 7.0 (e.g. on older CPUs without AVX2)
MONGO_VERSION="7.0" setup_mongodb


setup_mysql


Description


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


# 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


setup_nodejs


Description


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


# 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


setup_php


Description


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


# 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


setup_postgresql


Description


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


# 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


setup_ruby


Description


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


# 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


setup_clickhouse


Description


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


# Install latest ClickHouse
setup_clickhouse

# Install a specific ClickHouse version
CLICKHOUSE_VERSION="24.3.2.20" setup_clickhouse


setup_rust


Description


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


# 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


setup_uv


Description


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


# 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


_install_uvx_wrapper


Description


    

  • 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


# Install or update yq
setup_yq

# Example usage in scripts
yq '.services[].name' docker-compose.yml


              


          



  
          

            


            
Clone this wiki locally