ProxmoxVED/docs/misc/tools.func/README.md

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

• build.func/ - Container creation orchestrator
• core.func/ - Utility functions and messaging
• install.func/ - Installation workflow management
• error_handler.func/ - Error handling and recovery
• UPDATED_APP-install.md - Application script guide

---

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