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

tools.func Integration Guide

How tools.func integrates with other components and provides package/tool services to the ProxmoxVED ecosystem.

Component Relationships

tools.func in the Installation Pipeline

ct/AppName.sh (host)
    │
    ├─ Calls build.func
    │
    └─ Creates Container
            │
            ▼
install/appname-install.sh (container)
            │
            ├─ Sources: core.func (colors, messaging)
            ├─ Sources: error_handler.func (error handling)
            ├─ Sources: install.func (container setup)
            │
            └─ ★ Sources: tools.func ★
                        │
                        ├─ pkg_update()
                        ├─ pkg_install()
                        ├─ setup_nodejs()
                        ├─ setup_php()
                        ├─ setup_mariadb()
                        └─ ... 30+ functions

Integration with core.func

tools.func uses core.func for:

• msg_info() - Display progress messages
• msg_ok() - Display success messages
• msg_error() - Display error messages
• msg_warn() - Display warnings
• Color codes (GN, RD, YW, BL) for formatted output
• $STD variable - Output suppression control

Example:

# tools.func internally calls:
msg_info "Installing Node.js"      # Uses core.func
setup_nodejs "20"                  # Setup happens
msg_ok "Node.js installed"         # Uses core.func

Integration with error_handler.func

tools.func uses error_handler.func for:

• Exit code mapping to error descriptions
• Automatic error trapping (catch_errors)
• Signal handlers (SIGINT, SIGTERM, EXIT)
• Structured error reporting

Example:

# If setup_nodejs fails, error_handler catches it:
catch_errors    # Calls from error_handler.func
setup_nodejs "20"  # If this exits non-zero
                   # error_handler logs and traps it

Integration with install.func

tools.func coordinates with install.func for:

• Initial OS updates (install.func) → then tools (tools.func)
• Network verification before tool installation
• Package manager state validation
• Cleanup procedures after tool setup

Sequence:

setting_up_container()      # From install.func
network_check()             # From install.func
update_os()                 # From install.func

pkg_update                  # From tools.func
setup_nodejs()              # From tools.func

motd_ssh()                  # From install.func
customize()                 # From install.func
cleanup_lxc()               # From install.func

---

Integration with alpine-tools.func (Alpine Containers)

When to Use tools.func vs alpine-tools.func

Feature	tools.func (Debian)	alpine-tools.func (Alpine)
Package Manager	apt-get	apk
Installation Scripts	install/*.sh	install/*-alpine.sh
Tool Setup	setup_nodejs() (apt)	setup_nodejs() (apk)
Repository	setup_deb822_repo()	add_community_repo()
Services	systemctl	rc-service

Automatic Selection

Installation scripts detect OS and source appropriate functions:

# install/myapp-install.sh
if grep -qi 'alpine' /etc/os-release; then
  # Alpine detected - uses alpine-tools.func
  apk_update
  apk_add package
else
  # Debian detected - uses tools.func
  pkg_update
  pkg_install package
fi

---

Dependencies Management

External Dependencies

tools.func requires:
├─ curl          (for HTTP requests, GPG keys)
├─ wget          (for downloads)
├─ apt-get       (package manager)
├─ gpg           (GPG key management)
├─ openssl       (for encryption)
└─ systemctl     (service management on Debian)

Internal Function Dependencies

setup_nodejs()
    ├─ Calls: setup_deb822_repo()
    ├─ Calls: pkg_update()
    ├─ Calls: pkg_install()
    └─ Uses: msg_info(), msg_ok() [from core.func]

setup_mariadb()
    ├─ Calls: setup_deb822_repo()
    ├─ Calls: pkg_update()
    ├─ Calls: pkg_install()
    └─ Uses: msg_info(), msg_ok()

setup_docker()
    ├─ Calls: cleanup_repo_metadata()
    ├─ Calls: setup_deb822_repo()
    ├─ Calls: pkg_update()
    └─ Uses: msg_info(), msg_ok()

---

Function Call Graph

Complete Installation Dependency Tree

install/app-install.sh
    │
    ├─ setting_up_container()         [install.func]
    │
    ├─ network_check()                [install.func]
    │
    ├─ update_os()                    [install.func]
    │
    ├─ pkg_update()                   [tools.func]
    │   └─ Calls: apt-get update (with retry)
    │
    ├─ setup_nodejs("20")             [tools.func]
    │   ├─ setup_deb822_repo()        [tools.func]
    │   │   └─ Calls: apt-get update
    │   ├─ pkg_update()               [tools.func]
    │   └─ pkg_install()              [tools.func]
    │
    ├─ setup_php("8.3")               [tools.func]
    │   └─ Similar to setup_nodejs
    │
    ├─ setup_mariadb("11")            [tools.func]
    │   └─ Similar to setup_nodejs
    │
    ├─ motd_ssh()                     [install.func]
    │
    ├─ customize()                    [install.func]
    │
    └─ cleanup_lxc()                  [install.func]

---

Configuration Management

Environment Variables Used by tools.func

# Output control
STD="silent"              # Suppress apt/apk output
VERBOSE="yes"             # Show all output

# Package management
DEBIAN_FRONTEND="noninteractive"

# Tool versions (optional)
NODEJS_VERSION="20"
PHP_VERSION="8.3"
POSTGRES_VERSION="16"

Tools Configuration Files Created

/opt/
├─ nodejs_version.txt       # Node.js version
├─ php_version.txt          # PHP version
├─ mariadb_version.txt      # MariaDB version
├─ postgresql_version.txt   # PostgreSQL version
├─ docker_version.txt       # Docker version
└─ [TOOL]_version.txt       # For all installed tools

/etc/apt/sources.list.d/
├─ nodejs.sources           # Node.js repo (deb822)
├─ docker.sources           # Docker repo (deb822)
└─ [name].sources           # Other repos (deb822)

---

Error Handling Integration

Exit Codes from tools.func

Code	Meaning	Handled By
0	Success	Normal flow
1	Package installation failed	error_handler.func
100-101	APT error	error_handler.func
127	Command not found	error_handler.func

Automatic Cleanup on Failure

# If any step fails in install script:
catch_errors
pkg_update        # Fail here?
setup_nodejs      # Doesn't get here

# error_handler automatically:
├─ Logs error
├─ Captures exit code
├─ Calls cleanup_lxc()
└─ Exits with proper code

---

Integration with build.func

Variable Flow

ct/app.sh
    │
    ├─ var_cpu="2"
    ├─ var_ram="2048"
    ├─ var_disk="10"
    │
    └─ Calls: build_container()     [build.func]
              │
              └─ Creates container
                 │
                 └─ Calls: install/app-install.sh
                    │
                    └─ Uses: tools.func for installation

Resource Considerations

tools.func respects container resource limits:

• Large package installations respect allocated RAM
• Database setups use allocated disk space
• Build tools (gcc, make) stay within CPU allocation

---

Version Management

How tools.func Tracks Versions

Each tool installation creates a version file:

# setup_nodejs() creates:
echo "20.10.5" > /opt/nodejs_version.txt

# Used by update scripts:
CURRENT=$(cat /opt/nodejs_version.txt)
LATEST=$(curl ... # fetch latest)
if [[ "$LATEST" != "$CURRENT" ]]; then
  # Update needed
fi

Integration with Update Functions

# In ct/app.sh:
function update_script() {
  # Check Node version
  RELEASE=$(curl ... | jq '.version')
  CURRENT=$(cat /opt/nodejs_version.txt)

  if [[ "$RELEASE" != "$CURRENT" ]]; then
    # Use tools.func to upgrade
    setup_nodejs "$RELEASE"
  fi
}

---

Best Practices for Integration

✅ DO

1. Call functions in proper order

   pkg_update
   setup_tool "version"
   

2. Use $STD for production

   export STD="silent"
   pkg_install curl wget
   

3. Check for existing installations

   command -v nodejs >/dev/null || setup_nodejs "20"
   

4. Coordinate with install.func

   setting_up_container
   update_os                    # From install.func
   setup_nodejs                 # From tools.func
   motd_ssh                     # Back to install.func
   

❌ DON'T

1. Don't skip pkg_update

   # Bad - may fail due to stale cache
   pkg_install curl
   

2. Don't hardcode versions

   # Bad
   apt-get install nodejs=20.x
   
   # Good
   setup_nodejs "20"
   

3. Don't mix package managers

   # Bad
   apt-get install curl
   apk add wget
   

4. Don't ignore errors

   # Bad
   setup_docker || true
   
   # Good
   if ! setup_docker; then
     msg_error "Docker failed"
     exit 1
   fi
   

---

Troubleshooting Integration Issues

"Package installation fails"

• Check: pkg_update was called first
• Check: Package name is correct for OS
• Solution: Manually verify in container

"Tool not accessible after installation"

• Check: Tool added to PATH
• Check: Version file created
• Solution: which toolname to verify

"Repository conflicts"

• Check: No duplicate repositories
• Solution: cleanup_repo_metadata() before adding

"Alpine-specific errors when using Debian tools"

• Problem: Using tools.func functions on Alpine
• Solution: Use alpine-tools.func instead

---

Last Updated: December 2025 Maintainers: community-scripts team Integration Status: All components fully integrated