From a81255d472430a3d5e35efcd12f014103a4e6696 Mon Sep 17 00:00:00 2001 From: CanbiZ <47820557+MickLesk@users.noreply.github.com> Date: Mon, 10 Nov 2025 08:56:55 +0100 Subject: [PATCH] Updated tools.func (markdown) --- tools.func.md | 913 ++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 658 insertions(+), 255 deletions(-) diff --git a/tools.func.md b/tools.func.md index f47bc41..1beef7a 100644 --- a/tools.func.md +++ b/tools.func.md @@ -2,6 +2,7 @@ _Auto-generated from comments in `tools.func`. Each entry shows the purpose and usage of the function, where available._ + ## `cache_installed_version` **Description** @@ -445,12 +446,40 @@ manage_tool_repository "mariadb" "11.4" "https://repo..." "GPG_key_url" ## `setup_deb822_repo` -**Description** +### Description -- ------------------------------------------------------------------------------ -- Standardized deb822 repository setup (with optional Architectures) -- Always runs apt update after repo creation to ensure package availability -- ------------------------------------------------------------------------------ +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/.gpg`. +- Writes `/etc/apt/sources.list.d/.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` @@ -595,14 +624,31 @@ manage_tool_repository "mariadb" "11.4" "https://repo..." "GPG_key_url" ## `download_with_progress` -**Description** +### Description -- ------------------------------------------------------------------------------ -- Downloads file with optional progress indicator using pv. -- Arguments: -- $1 - URL -- $2 - Destination path -- ------------------------------------------------------------------------------ +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` @@ -618,48 +664,145 @@ manage_tool_repository "mariadb" "11.4" "https://repo..." "GPG_key_url" ## `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** +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 [mode] [version] [target] [asset_pattern] +``` +- **`app`** (required) + Logical application name (used for log messages and version cache file at `$HOME/.`). + 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. + - `` – 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/`) + - 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//releases` endpoint, using `/latest` or `/tags/` 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/.`. + - 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//archive/refs/tags/v.tar.gz`. + - Downloads `-.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: `` + - 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) + +```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" ``` @@ -679,295 +822,547 @@ manage_tool_repository "mariadb" "11.4" "https://repo..." "GPG_key_url" ## `setup_adminer` -**Description** +### 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 -- ------------------------------------------------------------------------------ +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** +### 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 -- ------------------------------------------------------------------------------ +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** +### 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 -- ------------------------------------------------------------------------------ +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** +### 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) -- ------------------------------------------------------------------------------ +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** +### Description -- ------------------------------------------------------------------------------ -- Installs or updates Ghostscript (gs) from source. -- Description: -- - Fetches latest release -- - Builds and installs system-wide -- ------------------------------------------------------------------------------ +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** +### 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. -- ------------------------------------------------------------------------------ +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** +### 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. -- ------------------------------------------------------------------------------ +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** +### 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) -- ------------------------------------------------------------------------------ +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--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** +### Description -- ------------------------------------------------------------------------------ -- Installs a local IP updater script using networkd-dispatcher. -- Description: -- - Stores current IP in /run/local-ip.env -- - Automatically runs on network changes -- ------------------------------------------------------------------------------ +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=` into `/run/local-ip.env` whenever the IP changes. +- Uses `cache_installed_version` to track helper version (`local-ip-helper`). -## `get_current_ip` +### 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** +### 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) -- ------------------------------------------------------------------------------ +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` -**Description** +### 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) -- ------------------------------------------------------------------------------ +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 + +```bash +# 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** +### 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) -- ------------------------------------------------------------------------------ +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 + +```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 +``` ## `setup_nodejs` -**Description** +### 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") -- ------------------------------------------------------------------------------ +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 + +```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 +``` ## `setup_php` -**Description** +### 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) -- ------------------------------------------------------------------------------ +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-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 + +```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 +``` ## `setup_postgresql` -**Description** +### 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) +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__v.sql`. +- Configures the `apt.postgresql.org` repository via `manage_tool_repository`. +- Installs or upgrades the target `postgresql-` packages. +- Optionally installs additional `postgresql--` 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 + +```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 +``` ## `setup_ruby` -**Description** +### 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) -- ------------------------------------------------------------------------------ +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 + +```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 +``` ## `setup_clickhouse` -**Description** +### 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) -- ------------------------------------------------------------------------------ +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 + +```bash +# Install latest ClickHouse +setup_clickhouse + +# Install a specific ClickHouse version +CLICKHOUSE_VERSION="24.3.2.20" setup_clickhouse +``` ## `setup_rust` -**Description** +### 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") -- ------------------------------------------------------------------------------ +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 + +```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 +``` ## `setup_uv` -**Description** +### 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 -- ------------------------------------------------------------------------------ +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 + +```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 +``` ## `_install_uvx_wrapper` @@ -979,13 +1374,21 @@ manage_tool_repository "mariadb" "11.4" "https://repo..." "GPG_key_url" ## `setup_yq` -**Description** +### 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 -- ------------------------------------------------------------------------------ +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 + +```bash +# Install or update yq +setup_yq + +# Example usage in scripts +yq '.services[].name' docker-compose.yml +```