3998b80194
Introduced new and updated documentation files across the docs/ directory, including project structure guides, function library references, and standardized READMEs for ct, install, vm, tools, api, and misc. This update fully documents all nine function libraries, provides quick start and learning paths, and mirrors the project structure for easier navigation and contribution.
419 lines
9.8 KiB
Markdown
419 lines
9.8 KiB
Markdown
# 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**:
|
|
```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
|