github: extend docs / contribution / templates (#10921)

* Enhance setup-fork.sh with --full mode and misc/ targeting Added a new --full flag to setup-fork.sh to allow updating all files, not just those in misc/. Updated documentation and usage examples to clarify the new behavior. Improved file search and replacement logic for broader compatibility and flexibility. * add AI.md * fix links in AI.md * Update contribution docs and templates for best practices Refreshed AI.md with new reference scripts, expanded checklist, and improved AI assistant tips. Updated container and install script templates for modern defaults (Debian 13, larger disk, two tags), clarified helper function usage, and improved update/backup patterns. Enhanced JSON template with realistic metadata, new fields, and example notes. * Update fetch_and_deploy_gh_release usage in docs and templates Standardize the usage of fetch_and_deploy_gh_release by specifying all arguments, including mode, version, and target directory, in AI.md and template scripts. This clarifies the function's usage and ensures consistency across documentation and install/update templates. * Revise contribution docs and update CT template Expanded and clarified contribution documentation for forking, local development, cherry-picking, and AI-assisted code generation. Improved explanations for setup-fork.sh, local testing, and PR submission. Enhanced the container script template with detailed comments, clearer update_script structure, and step-by-step guidance for maintainers and contributors. * Update fork and release instructions in contribution docs Replaced placeholder GitHub repo references with 'YourUsername/YourRepo' throughout documentation for clarity. Expanded explanations in FORK_SETUP.md and README.md to clarify the difference between development and production script execution, and emphasized the importance of cherry-picking only relevant files for PRs. Updated install script template examples to use the new repo placeholder. * Update GitHub repo placeholders in docs and templates Replaced 'YourUsername/YourRepo' with 'owner/repo' in documentation and template scripts for consistency and clarity. This change standardizes example usage and reduces confusion for contributors. * Move user submitted guides to guides directory Renamed USER_SUBMITTED_GUIDES.md from docs/contribution to docs/guides for improved documentation organization. * Update contribution docs for improved workflow and clarity Revised multiple documentation files to clarify the recommended development workflow: contributors must test scripts via curl from their GitHub fork (not local bash), use setup-fork.sh for URL rewriting, and submit only new files using cherry-pick. Expanded and modernized install and JSON metadata template guides, emphasizing use of helper functions, resource requirements, and the JSON generator tool. Added detailed step-by-step instructions, best practices, and updated examples throughout. * Update contribution docs for new file structure Updated documentation to reflect the migration of install scripts from install_scripts/ to install/, and JSON metadata from config/ to frontend/public/json/. Adjusted all relevant paths, instructions, and examples to match the new directory structure for improved clarity and consistency. * Update contribution docs for fork setup and metadata Revised documentation to standardize use of 'bash docs/contribution/setup-fork.sh --full' for fork configuration, clarified install script execution flow, and updated JSON metadata template and field references. Improved helper function docs, resource requirements, and category lists. Updated references and instructions throughout for consistency and accuracy. * Docs: add GPU/TUN, update endpoints & tool refs Documentation updates across guides and function references: - Added var_gpu and var_tun configuration entries to CONFIGURATION_REFERENCE (GPU passthrough and TUN/TAP support), including features and prerequisites. - Fixed repository URLs throughout UNATTENDED_DEPLOYMENTS and examples: replaced community-scripts/ProxmoxVED with community-scripts/ProxmoxVE and updated curl usage to the new paths. - Added an "Advanced Configuration Variables" table and examples (var_os, var_version, var_gpu, var_tun, var_nesting) to UNATTENDED_DEPLOYMENTS; adjusted sample apps, hostnames, and container mappings in batch examples. - Switched API endpoints in API_FUNCTIONS_REFERENCE and API_USAGE_EXAMPLES from http://api.community-scripts.org to https://api.community-scripts.org. - Expanded BUILD_FUNC_FUNCTIONS_REFERENCE with container resource/ID management helper descriptions (validate_container_id, get_valid_container_id, maxkeys_check, get_current_ip, update_motd_ip). - Large edits to TOOLS_FUNC_FUNCTIONS_REFERENCE: renamed/refactored helper signatures and docs (pkg_install -> install_packages_with_retry, pkg_update -> upgrade_packages_with_retry), added new tooling functions (fetch_and_deploy_gh_release, check_for_gh_release, prepare_repository_setup, verify_tool_version) and updated examples and feature notes. - Updated vm/README.md to list additional VM scripts (new and reorganized examples). These are documentation-only changes to clarify configuration options, correct links and endpoints, and expand the reference material for tooling and build helpers. * Docs: expand developer/debugging and tools references Add extensive documentation and examples across contribution, guides, templates and tools references. Key changes: - Introduce a Developer Mode & Debugging section (dev_mode flags: trace, keep, pause, breakpoint, logs, dryrun, motd) in CONTRIBUTING.md with usage example. - Provide a standard update_script() pattern and BookStack example in GUIDE.md to clarify update flow (stop services, backup, deploy, restore, migrate, restart). - Add new helper entries (BookLore, KaraKeep) and advanced repository helpers (setup_deb822_repo, prepare_repository_setup, cleanup_tool_keyrings) plus utilities (setup_meilisearch, verify_tool_version) in HELPER_FUNCTIONS.md. - Update install template to suggest PNPM, Java 21 and Meilisearch; update example DB setup notes in AppName-install.sh. - Add var_diagnostics option and switch var_fuse to boolean/toggle wording in CONFIGURATION_REFERENCE.md; clarify privacy and defaults. - Adjust example container definitions in UNATTENDED_DEPLOYMENTS.md (container entries and resource values). - Change storage and flag variables and examples in BUILD_FUNC_USAGE_EXAMPLES.md (ssd-storage, var_fuse/var_tun, etc.). - Expand TOOLS_FUNC_FUNCTIONS_REFERENCE.md with many setup_* function signatures, environment vars, clarified fetch_and_deploy_gh_release modes/parameters, and additional tool docs (nodejs, php, mariadb_db, postgresql_db, java, uv, yq, meilisearch, composer, build tools). These updates improve onboarding, debugging guidance, and operational clarity for contributors and maintainers.
2026-04-18 08:22:16 +00:00 · 2026-02-05 16:45:41 +01:00
parent c576728833
commit cb939861b8
23 changed files with 2906 additions and 740 deletions
--- a/docs/misc/tools.func/TOOLS_FUNC_FUNCTIONS_REFERENCE.md
+++ b/docs/misc/tools.func/TOOLS_FUNC_FUNCTIONS_REFERENCE.md
@@ -20,14 +20,19 @@ Complete alphabetical reference of all functions in tools.func with parameters,
 - `setup_nodejs(VERSION)` - Install Node.js and npm
 - `setup_php(VERSION)` - Install PHP-FPM and CLI
 - `setup_python(VERSION)` - Install Python 3 with pip
+- `setup_uv()` - Install Python uv (modern & fast)
 - `setup_ruby(VERSION)` - Install Ruby with gem
 - `setup_golang(VERSION)` - Install Go programming language
+- `setup_java(VERSION)` - Install OpenJDK (Adoptium)

 **Databases**:
- `setup_mariadb()` - Install MariaDB server (distro packages by default)
+- `setup_mariadb()` - Install MariaDB server
+- `setup_mariadb_db()` - Create user/db in MariaDB
 - `setup_postgresql(VERSION)` - Install PostgreSQL
+- `setup_postgresql_db()` - Create user/db in PostgreSQL
 - `setup_mongodb(VERSION)` - Install MongoDB
 - `setup_redis(VERSION)` - Install Redis cache
+- `setup_meilisearch()` - Install Meilisearch engine

 **Web Servers**:
 - `setup_nginx()` - Install Nginx
@@ -44,6 +49,7 @@ Complete alphabetical reference of all functions in tools.func with parameters,
 - `setup_docker_compose()` - Install Docker Compose
 - `setup_composer()` - Install PHP Composer
 - `setup_build_tools()` - Install build-essential
+- `setup_yq()` - Install mikefarah/yq processor

 **Monitoring**:
 - `setup_grafana()` - Install Grafana
@@ -60,13 +66,13 @@ Complete alphabetical reference of all functions in tools.func with parameters,

 ## Core Functions

-### pkg_install()
+### install_packages_with_retry()

-Install one or more packages safely with automatic retry logic and error handling.
+Install one or more packages safely with automatic retry logic (3 attempts), APT refresh, and lock handling.

 **Signature**:
 ```bash
-pkg_install PACKAGE1 [PACKAGE2 ...]
+install_packages_with_retry PACKAGE1 [PACKAGE2 ...]
 ```

 **Parameters**:
@@ -74,66 +80,122 @@ pkg_install PACKAGE1 [PACKAGE2 ...]

 **Returns**:
 - `0` - All packages installed successfully
- `1` - Installation failed after retries
+- `1` - Installation failed after all retries
+
+**Features**:
+- Automatically sets `DEBIAN_FRONTEND=noninteractive`
+- Handles DPKG lock errors with `dpkg --configure -a`
+- Retries on transient network or APT failures
+
+**Example**:
+```bash
+install_packages_with_retry curl wget git
+```
+
+---
+
+### upgrade_packages_with_retry()
+
+Upgrades installed packages with the same robust retry logic as the installation helper.
+
+**Signature**:
+```bash
+upgrade_packages_with_retry
+```
+
+**Returns**:
+- `0` - Upgrade successful
+- `1` - Upgrade failed
+
+---
+
+### fetch_and_deploy_gh_release()
+
+The primary tool for downloading and installing software from GitHub Releases. Supports binaries, tarballs, and Debian packages.
+
+**Signature**:
+```bash
+fetch_and_deploy_gh_release APPREPO TYPE [VERSION] [DEST] [ASSET_PATTERN]
+```

 **Environment Variables**:
- `$STD` - Output suppression (`silent` or empty)
+- `APPREPO`: GitHub repository (e.g., `owner/repo`)
+- `TYPE`: Asset type (`binary`, `tarball`, `prebuild`, `singlefile`)
+- `VERSION`: Specific tag or `latest` (Default: `latest`)
+- `DEST`: Target directory (Default: `/opt/$APP`)
+- `ASSET_PATTERN`: Regex or string pattern to match the release asset (Required for `prebuild` and `singlefile`)
+
+**Supported Operation Modes**:
+- `tarball`: Downloads and extracts the source tarball.
+- `binary`: Detects host architecture and installs a `.deb` package using `apt` or `dpkg`.
+- `prebuild`: Downloads and extracts a pre-built binary archive (supports `.tar.gz`, `.zip`, `.tgz`, `.txz`).
+- `singlefile`: Downloads a single binary file to the destination.
+
+**Environment Variables**:
+- `CLEAN_INSTALL=1`: Removes all contents of the destination directory before extraction.
+- `DPKG_FORCE_CONFOLD=1`: Forces `dpkg` to keep old config files during package updates.
+- `SYSTEMD_OFFLINE=1`: Used automatically for `.deb` installs to prevent systemd-tmpfiles failures in unprivileged containers.

 **Example**:
 ```bash
-pkg_install curl wget git
+fetch_and_deploy_gh_release "muesli/duf" "binary" "latest" "/opt/duf" "duf_.*_linux_amd64.tar.gz"
 ```

 ---

-### pkg_update()
+### check_for_gh_release()

-Update package lists with automatic retry logic for network failures.
+Checks if a newer version is available on GitHub compared to the installed version.

 **Signature**:
 ```bash
-pkg_update
+check_for_gh_release APP REPO
 ```

-**Parameters**: None
-
-**Returns**:
- `0` - Package lists updated
- `1` - Failed after 3 retries
-
 **Example**:
 ```bash
-pkg_update
+if check_for_gh_release "nodejs" "nodesource/distributions"; then
+  # update logic
+fi
 ```

 ---

-### pkg_remove()
+### prepare_repository_setup()

-Remove packages completely including dependencies.
+Performs safe repository preparation by cleaning up old files, keyrings, and ensuring the APT system is in a working state.

 **Signature**:
 ```bash
-pkg_remove PACKAGE1 [PACKAGE2 ...]
+prepare_repository_setup REPO_NAME [REPO_NAME2 ...]
 ```

-**Parameters**:
- `PACKAGE1, PACKAGE2, ...` - Package names to remove
-
-**Returns**:
- `0` - Packages removed
- `1` - Removal failed
-
 **Example**:
 ```bash
-pkg_remove old-package outdated-tool
+prepare_repository_setup "mariadb" "mysql"
+```
+
+---
+
+### verify_tool_version()
+
+Validates if the installed major version matches the expected version.
+
+**Signature**:
+```bash
+verify_tool_version NAME EXPECTED INSTALLED
+```
+
+**Example**:
+```bash
+verify_tool_version "nodejs" "22" "$(node -v | grep -oP '^v\K[0-9]+')"
 ```

 ---

 ### setup_deb822_repo()

-Add repository in modern deb822 format (recommended over legacy format).
+Add repository in modern deb822 format.

 **Signature**:
 ```bash
@@ -188,12 +250,234 @@ cleanup_repo_metadata

 ## Tool Installation Functions

-### setup_nodejs(VERSION)
+### setup_nodejs()

-Install Node.js and npm from official repositories.
+Install Node.js and npm from official repositories. Handles legacy version cleanup (nvm) automatically.

 **Signature**:
 ```bash
+setup_nodejs
+```
+
+**Environment Variables**:
+- `NODE_VERSION`: Major version to install (e.g. "20", "22", "24"). Default: "24".
+- `NODE_MODULE`: Optional npm package to install globally during setup (e.g. "pnpm", "yarn").
+
+**Example**:
+```bash
+NODE_VERSION="22" NODE_MODULE="pnpm" setup_nodejs
+```
+
+---
+
+### setup_php()
+
+Install PHP with configurable extensions and FPM/Apache integration.
+
+**Signature**:
+```bash
+setup_php
+```
+
+**Environment Variables**:
+- `PHP_VERSION`: Version to install (e.g. "8.3", "8.4"). Default: "8.4".
+- `PHP_MODULE`: Comma-separated list of additional extensions.
+- `PHP_FPM`: Set to "YES" to install php-fpm.
+- `PHP_APACHE`: Set to "YES" to install libapache2-mod-php.
+
+**Example**:
+```bash
+PHP_VERSION="8.3" PHP_FPM="YES" PHP_MODULE="mysql,xml,zip" setup_php
+```
+
+---
+
+### setup_mariadb_db()
+
+Creates a new MariaDB database and a dedicated user with all privileges. Automatically generates a password if not provided and saves it to a credentials file.
+
+**Environment Variables**:
+- `MARIADB_DB_NAME`: Name of the database (required)
+- `MARIADB_DB_USER`: Name of the database user (required)
+- `MARIADB_DB_PASS`: User password (optional, auto-generated if omitted)
+
+**Example**:
+```bash
+MARIADB_DB_NAME="myapp" MARIADB_DB_USER="myapp_user" setup_mariadb_db
+```
+
+---
+
+### setup_postgresql_db()
+
+Creates a new PostgreSQL database and a dedicated user/role with all privileges. Automatically generates a password if not provided and saves it to a credentials file.
+
+**Environment Variables**:
+- `PG_DB_NAME`: Name of the database (required)
+- `PG_DB_USER`: Name of the database user (required)
+- `PG_DB_PASS`: User password (optional, auto-generated if omitted)
+
+---
+
+### setup_java()
+
+Installs Temurin JDK.
+
+**Signature**:
+```bash
+JAVA_VERSION="21" setup_java
+```
+
+**Parameters**:
+- `JAVA_VERSION` - JDK version (e.g., "17", "21") (default: "21")
+
+**Example**:
+```bash
+JAVA_VERSION="17" setup_java
+```
+
+---
+
+### setup_uv()
+
+Installs `uv` (modern Python package manager).
+
+**Signature**:
+```bash
+PYTHON_VERSION="3.13" setup_uv
+```
+
+**Parameters**:
+- `PYTHON_VERSION` - Optional Python version to pre-install via uv (e.g., "3.12", "3.13")
+
+**Example**:
+```bash
+PYTHON_VERSION="3.13" setup_uv
+```
+
+---
+
+### setup_go()
+
+Installs Go programming language.
+
+**Signature**:
+```bash
+GO_VERSION="1.23" setup_go
+```
+
+**Parameters**:
+- `GO_VERSION` - Go version to install (default: "1.23")
+
+**Example**:
+```bash
+GO_VERSION="1.24" setup_go
+```
+
+---
+
+### setup_yq()
+
+Installs `yq` (YAML processor).
+
+**Signature**:
+```bash
+setup_yq
+```
+
+**Example**:
+```bash
+setup_yq
+```
+
+---
+
+### setup_composer()
+
+Installs PHP Composer.
+
+**Signature**:
+```bash
+setup_composer
+```
+
+**Example**:
+```bash
+setup_composer
+```
+
+---
+
+### setup_meilisearch()
+
+Install and configure Meilisearch search engine.
+
+**Environment Variables**:
+- `MEILISEARCH_BIND`: Address and port to bind to (Default: "127.0.0.1:7700")
+- `MEILISEARCH_ENV`: Environment mode (Default: "production")
+
+---
+
+### setup_yq()
+
+Install the `mikefarah/yq` YAML processor. Removes existing non-compliant versions.
+
+**Example**:
+```bash
+setup_yq
+yq eval '.app.version = "1.0.0"' -i config.yaml
+```
+
+---
+
+### setup_composer()
+
+Install or update the PHP Composer package manager. Handles `COMPOSER_ALLOW_SUPERUSER` automatically and performs self-updates if already installed.
+
+**Example**:
+```bash
+setup_php
+setup_composer
+$STD composer install --no-dev
+```
+
+---
+
+### setup_build_tools()
+
+Install the `build-essential` package suite for compiling software.
+
+---
+
+### setup_uv()
+
+Install the modern Python package manager `uv`. Extremely fast replacement for pip/venv.
+
+**Environment Variables**:
+- `PYTHON_VERSION`: Major.Minor version to ensure is installed.
+
+**Example**:
+```bash
+PYTHON_VERSION="3.12" setup_uv
+uv sync --locked
+```
+
+---
+
+### setup_java()
+
+Install OpenJDK via the Adoptium repository.
+
+**Environment Variables**:
+- `JAVA_VERSION`: Major version to install (e.g. "17", "21"). Default: "21".
+
+**Example**:
+```bash
+JAVA_VERSION="21" setup_java
+```
+
+---
+```bash
 setup_nodejs VERSION
 ```