mirror of
https://github.com/community-scripts/ProxmoxVE.git
synced 2025-12-26 17:06:24 +01:00
add comprehensive documentation (#9537)
This commit is contained in:
CanbiZ
418
docs/misc/tools.func/TOOLS_FUNC_INTEGRATION.md
Normal file
418
docs/misc/tools.func/TOOLS_FUNC_INTEGRATION.md
Normal file
@ -0,0 +1,418 @@
|
||||
# tools.func Integration Guide
|
||||
|
||||
How tools.func integrates with other components and provides package/tool services to the ProxmoxVE 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**:
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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**
|
||||
```bash
|
||||
pkg_update
|
||||
setup_tool "version"
|
||||
```
|
||||
|
||||
2. **Use $STD for production**
|
||||
```bash
|
||||
export STD="silent"
|
||||
pkg_install curl wget
|
||||
```
|
||||
|
||||
3. **Check for existing installations**
|
||||
```bash
|
||||
command -v nodejs >/dev/null || setup_nodejs "20"
|
||||
```
|
||||
|
||||
4. **Coordinate with install.func**
|
||||
```bash
|
||||
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**
|
||||
```bash
|
||||
# Bad - may fail due to stale cache
|
||||
pkg_install curl
|
||||
```
|
||||
|
||||
2. **Don't hardcode versions**
|
||||
```bash
|
||||
# Bad
|
||||
apt-get install nodejs=20.x
|
||||
|
||||
# Good
|
||||
setup_nodejs "20"
|
||||
```
|
||||
|
||||
3. **Don't mix package managers**
|
||||
```bash
|
||||
# Bad
|
||||
apt-get install curl
|
||||
apk add wget
|
||||
```
|
||||
|
||||
4. **Don't ignore errors**
|
||||
```bash
|
||||
# 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
|
||||
Reference in New Issue
Block a user