community-scripts/ProxmoxVE
5
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
ProxmoxVE/docs/misc/tools.func/README.md
CanbiZ 1294b89fcb
add comprehensive documentation (#9537)
2025-12-01 13:50:11 +01:00

7.9 KiB
Raw Blame History

tools.func Documentation

Overview

The tools.func file provides a comprehensive collection of helper functions for robust package management, repository management, and tool installation in Debian/Ubuntu-based systems. It is the central hub for installing services, databases, programming languages, and development tools in containers.

Purpose and Use Cases

  • Package Management: Robust APT/DPKG operations with retry logic
  • Repository Setup: Prepare and configure package repositories safely
  • Tool Installation: Install 30+ tools (Node.js, PHP, databases, etc.)
  • Dependency Handling: Manage complex installation workflows
  • Error Recovery: Automatic recovery from network failures

Quick Reference

Key Function Groups

  • Package Helpers: pkg_install(), pkg_update(), pkg_remove() - APT operations with retry
  • Repository Setup: setup_deb822_repo() - Modern repository configuration
  • Tool Installation: setup_nodejs(), setup_php(), setup_mariadb(), etc. - 30+ tool functions
  • System Utilities: disable_wait_online(), customize() - System optimization
  • Container Setup: setting_up_container(), motd_ssh() - Container initialization

Dependencies

  • External: curl, wget, apt-get, gpg
  • Internal: Uses functions from core.func, install.func, error_handler.func

Integration Points

  • Used by: All install scripts for dependency installation
  • Uses: Environment variables from build.func and core.func
  • Provides: Tool installation, package management, and repository services

Documentation Files

📊 TOOLS_FUNC_FLOWCHART.md

Visual execution flows showing package management, tool installation, and repository setup workflows.

📚 TOOLS_FUNC_FUNCTIONS_REFERENCE.md

Complete alphabetical reference of all 30+ functions with parameters, dependencies, and usage details.

💡 TOOLS_FUNC_USAGE_EXAMPLES.md

Practical examples showing how to use tool installation functions and common patterns.

🔗 TOOLS_FUNC_INTEGRATION.md

How tools.func integrates with other components and provides package/tool services.

🔧 TOOLS_FUNC_ENVIRONMENT_VARIABLES.md

Complete reference of environment variables and configuration options.

Key Features

Robust Package Management

  • Automatic Retry Logic: 3 attempts with backoff for transient failures
  • Silent Mode: Suppress output with $STD variable
  • Error Recovery: Automatic cleanup of broken packages
  • Atomic Operations: Ensure consistent state even on failure

Tool Installation Coverage

  • Node.js Ecosystem: Node.js, npm, yarn, pnpm
  • PHP Stack: PHP-FPM, PHP-CLI, Composer
  • Databases: MariaDB, PostgreSQL, MongoDB
  • Development Tools: Git, build-essential, Docker
  • Monitoring: Grafana, Prometheus, Telegraf
  • And 20+ more...

Repository Management

  • Deb822 Format: Modern standardized repository format
  • Keyring Handling: Automatic GPG key management
  • Cleanup: Removes legacy repositories and keyrings
  • Validation: Verifies repository accessibility before use

Common Usage Patterns

Installing a Tool

setup_nodejs "20"     # Install Node.js v20
setup_php "8.2"       # Install PHP 8.2
setup_mariadb "11"    # Install MariaDB 11

Safe Package Operations

pkg_update           # Update package lists with retry
pkg_install curl wget  # Install packages safely
pkg_remove old-tool   # Remove package cleanly

Setting Up Repositories

setup_deb822_repo "ppa:example/ppa" "example-app" "jammy" "http://example.com" "release"

Function Categories

🔹 Core Package Functions

  • pkg_install() - Install packages with retry logic
  • pkg_update() - Update package lists safely
  • pkg_remove() - Remove packages completely

🔹 Repository Functions

  • setup_deb822_repo() - Add repository in deb822 format
  • cleanup_repo_metadata() - Clean GPG keys and old repos
  • check_repository() - Verify repository is accessible

🔹 Tool Installation Functions (30+)

Programming Languages:

  • setup_nodejs() - Node.js with npm
  • setup_php() - PHP-FPM and CLI
  • setup_python() - Python 3 with pip
  • setup_ruby() - Ruby with gem
  • setup_golang() - Go programming language

Databases:

  • setup_mariadb() - MariaDB server
  • setup_postgresql() - PostgreSQL database
  • setup_mongodb() - MongoDB NoSQL
  • setup_redis() - Redis cache

Web Servers & Proxies:

  • setup_nginx() - Nginx web server
  • setup_apache() - Apache HTTP server
  • setup_caddy() - Caddy web server
  • setup_traefik() - Traefik reverse proxy

Containers & Virtualization:

  • setup_docker() - Docker container runtime
  • setup_podman() - Podman container runtime

Development & System Tools:

  • setup_git() - Git version control
  • setup_docker_compose() - Docker Compose
  • setup_composer() - PHP dependency manager
  • setup_build_tools() - C/C++ compilation tools

Monitoring & Logging:

  • setup_grafana() - Grafana dashboards
  • setup_prometheus() - Prometheus monitoring
  • setup_telegraf() - Telegraf metrics collector

🔹 System Configuration Functions

  • setting_up_container() - Container initialization message
  • network_check() - Verify network connectivity
  • update_os() - Update OS packages safely
  • customize() - Apply container customizations
  • motd_ssh() - Configure SSH and MOTD
  • cleanup_lxc() - Final container cleanup

Best Practices

✅ DO

  • Use $STD to suppress output in production scripts
  • Chain multiple tool installations together
  • Check for tool availability before using
  • Use version parameters when available
  • Test new repositories before production use

❌ DON'T

  • Mix package managers (apt and apk in same script)
  • Hardcode tool versions directly
  • Skip error checking on package operations
  • Use apt-get install -y without $STD
  • Leave temporary files after installation

Recent Updates

Version 2.0 (Dec 2025)

  • ✅ Added setup_deb822_repo() for modern repository format
  • ✅ Improved error handling with automatic cleanup
  • ✅ Added 5 new tool installation functions
  • ✅ Enhanced package retry logic with backoff
  • ✅ Standardized tool version handling

Integration with Other Functions

tools.func
    ├── Uses: core.func (messaging, colors)
    ├── Uses: error_handler.func (exit codes, trapping)
    ├── Uses: install.func (network_check, update_os)
    │
    └── Used by: All install/*.sh scripts
        ├── For: Package installation
        ├── For: Tool setup
        └── For: Repository management

Troubleshooting

"Package manager is locked"

# Wait for apt lock to release
sleep 10
pkg_update

"GPG key not found"

# Repository setup will handle this automatically
# If manual fix needed:
cleanup_repo_metadata
setup_deb822_repo ...

"Tool installation failed"

# Enable verbose output
export var_verbose="yes"
setup_nodejs "20"

Contributing

When adding new tool installation functions:

  1. Follow the setup_TOOLNAME() naming convention
  2. Accept version as first parameter
  3. Check if tool already installed
  4. Use $STD for output suppression
  5. Set version file: /opt/TOOLNAME_version.txt
  6. Document in TOOLS_FUNC_FUNCTIONS_REFERENCE.md

Related Documentation

Last Updated: December 2025 Maintainers: community-scripts team License: MIT