mirror of
https://github.com/community-scripts/ProxmoxVE.git
synced 2026-04-19 00:42:16 +00:00
cleanup: remove docs/, update README & CONTRIBUTING, fix repo config (#13770)
This commit is contained in:
CanbiZ (MickLesk)
committed by
GitHub
GitHub
parent
b2c0d7646e
commit
997e05dfb1
@@ -1,235 +0,0 @@
|
||||
# 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](./TOOLS_FUNC_FLOWCHART.md)
|
||||
Visual execution flows showing package management, tool installation, and repository setup workflows.
|
||||
|
||||
### 📚 [TOOLS_FUNC_FUNCTIONS_REFERENCE.md](./TOOLS_FUNC_FUNCTIONS_REFERENCE.md)
|
||||
Complete alphabetical reference of all 30+ functions with parameters, dependencies, and usage details.
|
||||
|
||||
### 💡 [TOOLS_FUNC_USAGE_EXAMPLES.md](./TOOLS_FUNC_USAGE_EXAMPLES.md)
|
||||
Practical examples showing how to use tool installation functions and common patterns.
|
||||
|
||||
### 🔗 [TOOLS_FUNC_INTEGRATION.md](./TOOLS_FUNC_INTEGRATION.md)
|
||||
How tools.func integrates with other components and provides package/tool services.
|
||||
|
||||
### 🔧 [TOOLS_FUNC_ENVIRONMENT_VARIABLES.md](./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
|
||||
```bash
|
||||
setup_nodejs "20" # Install Node.js v20
|
||||
setup_php "8.2" # Install PHP 8.2
|
||||
setup_mariadb # Install MariaDB (distribution packages)
|
||||
# MARIADB_VERSION="11.4" setup_mariadb # Specific version from official repo
|
||||
```
|
||||
|
||||
### Safe Package Operations
|
||||
```bash
|
||||
pkg_update # Update package lists with retry
|
||||
pkg_install curl wget # Install packages safely
|
||||
pkg_remove old-tool # Remove package cleanly
|
||||
```
|
||||
|
||||
### Setting Up Repositories
|
||||
```bash
|
||||
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"
|
||||
```bash
|
||||
# Wait for apt lock to release
|
||||
sleep 10
|
||||
pkg_update
|
||||
```
|
||||
|
||||
### "GPG key not found"
|
||||
```bash
|
||||
# Repository setup will handle this automatically
|
||||
# If manual fix needed:
|
||||
cleanup_repo_metadata
|
||||
setup_deb822_repo ...
|
||||
```
|
||||
|
||||
### "Tool installation failed"
|
||||
```bash
|
||||
# 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/](../build.func/)** - Container creation orchestrator
|
||||
- **[core.func/](../core.func/)** - Utility functions and messaging
|
||||
- **[install.func/](../install.func/)** - Installation workflow management
|
||||
- **[error_handler.func/](../error_handler.func/)** - Error handling and recovery
|
||||
- **[UPDATED_APP-install.md](../../UPDATED_APP-install.md)** - Application script guide
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: December 2025
|
||||
**Maintainers**: community-scripts team
|
||||
**License**: MIT
|
||||
@@ -1,199 +0,0 @@
|
||||
# tools.func Flowchart
|
||||
|
||||
## Main Package Installation Flow
|
||||
|
||||
```
|
||||
┌──────────────────────────────────┐
|
||||
│ Install Script Starts │
|
||||
│ source tools.func │
|
||||
└──────────────┬───────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ pkg_update()│
|
||||
│ (apt/apk) │
|
||||
└──────┬──────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────┐
|
||||
│ Retry Logic │ ◄─────┐
|
||||
│ (Up to 3 tries)│ │
|
||||
└────┬───────────┘ │
|
||||
│ │
|
||||
├─ Success: Continue │
|
||||
├─ Retry 1 ──────────┘
|
||||
└─ Fail: Exit
|
||||
│
|
||||
▼
|
||||
┌──────────────────┐
|
||||
│ setup_deb822_repo│
|
||||
│ (Add repository) │
|
||||
└────────┬─────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ GPG Key Setup │
|
||||
│ Verify Repo OK │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────┐
|
||||
│ Tool Installation│
|
||||
│ (setup_nodejs, │
|
||||
│ setup_php, etc.)│
|
||||
└────────┬─────────┘
|
||||
│
|
||||
┌──────────┴──────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────┐ ┌──────────────┐
|
||||
│ Node.js │ │ MariaDB │
|
||||
│ setup_ │ │ setup_ │
|
||||
│ nodejs() │ │ mariadb() │
|
||||
└──────┬──────┘ └────────┬─────┘
|
||||
│ │
|
||||
└────────┬───────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ Installation OK? │
|
||||
└────┬──────────┬───┘
|
||||
│ │
|
||||
YES NO
|
||||
│ │
|
||||
│ ▼
|
||||
│ ┌─────────────┐
|
||||
│ │ Rollback │
|
||||
│ │ Error Exit │
|
||||
│ └─────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Set Version File│
|
||||
│ /opt/TOOL_v.txt │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
## Repository Setup Flow (setup_deb822_repo)
|
||||
|
||||
```
|
||||
setup_deb822_repo(URL, name, dist, repo_url, release)
|
||||
│
|
||||
├─ Parse Parameters
|
||||
│ ├─ URL: Repository URL
|
||||
│ ├─ name: Repository name
|
||||
│ ├─ dist: Distro (jammy, bookworm)
|
||||
│ ├─ repo_url: Main URL
|
||||
│ └─ release: Release type
|
||||
│
|
||||
├─ Add GPG Key
|
||||
│ ├─ Download key from URL
|
||||
│ ├─ Add to keyring
|
||||
│ └─ Trust key for deb822
|
||||
│
|
||||
├─ Create deb822 file
|
||||
│ ├─ /etc/apt/sources.list.d/name.sources
|
||||
│ ├─ Format: DEB822
|
||||
│ └─ Include GPG key reference
|
||||
│
|
||||
├─ Validate Repository
|
||||
│ ├─ apt-get update
|
||||
│ ├─ Check for errors
|
||||
│ └─ Retry if needed
|
||||
│
|
||||
└─ Success / Error
|
||||
```
|
||||
|
||||
## Tool Installation Chain
|
||||
|
||||
```
|
||||
Tools to Install:
|
||||
├─ Programming Languages
|
||||
│ ├─ setup_nodejs(VERSION)
|
||||
│ ├─ setup_php(VERSION)
|
||||
│ ├─ setup_python(VERSION)
|
||||
│ ├─ setup_ruby(VERSION)
|
||||
│ └─ setup_golang(VERSION)
|
||||
│
|
||||
├─ Databases
|
||||
│ ├─ setup_mariadb(VERSION)
|
||||
│ ├─ setup_postgresql(VERSION)
|
||||
│ ├─ setup_mongodb(VERSION)
|
||||
│ └─ setup_redis(VERSION)
|
||||
│
|
||||
├─ Web Servers
|
||||
│ ├─ setup_nginx()
|
||||
│ ├─ setup_apache()
|
||||
│ ├─ setup_caddy()
|
||||
│ └─ setup_traefik()
|
||||
│
|
||||
├─ Containers
|
||||
│ ├─ setup_docker()
|
||||
│ └─ setup_podman()
|
||||
│
|
||||
└─ Utilities
|
||||
├─ setup_git()
|
||||
├─ setup_composer()
|
||||
├─ setup_build_tools()
|
||||
└─ setup_[TOOL]()
|
||||
```
|
||||
|
||||
## Package Operation Retry Logic
|
||||
|
||||
```
|
||||
┌─────────────────────┐
|
||||
│ pkg_install PKG1 │
|
||||
│ pkg_install PKG2 │
|
||||
│ pkg_install PKG3 │
|
||||
└──────────┬──────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ APT Lock Check │
|
||||
└────┬────────┬───┘
|
||||
│ │
|
||||
FREE LOCKED
|
||||
│ │
|
||||
│ ▼
|
||||
│ ┌─────────────┐
|
||||
│ │ Wait 5 sec │
|
||||
│ └────────┬────┘
|
||||
│ │
|
||||
│ ▼
|
||||
│ ┌─────────────┐
|
||||
│ │ Retry Check │
|
||||
│ └────┬────┬───┘
|
||||
│ │ │
|
||||
│ OK LOCK
|
||||
│ │ │
|
||||
│ └────┘ (loop)
|
||||
│
|
||||
▼
|
||||
┌──────────────────┐
|
||||
│ apt-get install │
|
||||
│ (with $STD) │
|
||||
└────┬─────────┬───┘
|
||||
│ │
|
||||
SUCCESS FAILED
|
||||
│ │
|
||||
│ ▼
|
||||
│ ┌──────────────┐
|
||||
│ │ Retry Count? │
|
||||
│ └────┬─────┬───┘
|
||||
│ │ │
|
||||
│ <3 ≥3 │
|
||||
│ Retry FAIL
|
||||
│ │
|
||||
│ └─────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────┐ ┌─────────┐
|
||||
│ SUCCESS │ │ FAILED │
|
||||
└─────────┘ │ EXIT 1 │
|
||||
└─────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Visual Reference for**: tools.func package management and tool installation
|
||||
**Last Updated**: December 2025
|
||||
@@ -1,784 +0,0 @@
|
||||
# tools.func Functions Reference
|
||||
|
||||
Complete alphabetical reference of all functions in tools.func with parameters, usage, and examples.
|
||||
|
||||
## Function Index
|
||||
|
||||
### Package Management
|
||||
- `pkg_install()` - Install packages safely with retry
|
||||
- `pkg_update()` - Update package lists with retry
|
||||
- `pkg_remove()` - Remove packages cleanly
|
||||
|
||||
### Repository Management
|
||||
- `setup_deb822_repo()` - Add repository in modern deb822 format
|
||||
- `cleanup_repo_metadata()` - Clean GPG keys and old repositories
|
||||
- `check_repository()` - Verify repository accessibility
|
||||
|
||||
### Tool Installation Functions (30+)
|
||||
|
||||
**Programming Languages**:
|
||||
- `setup_nodejs(VERSION)` - Install Node.js and npm
|
||||
- `setup_php(VERSION)` - Install PHP-FPM and CLI
|
||||
- `setup_python(VERSION)` - Install Python 3 with pip
|
||||
- `setup_uv()` - Install Python uv (modern & fast)
|
||||
- `setup_ruby(VERSION)` - Install Ruby with gem
|
||||
- `setup_golang(VERSION)` - Install Go programming language
|
||||
- `setup_java(VERSION)` - Install OpenJDK (Adoptium)
|
||||
|
||||
**Databases**:
|
||||
- `setup_mariadb()` - Install MariaDB server
|
||||
- `setup_mariadb_db()` - Create user/db in MariaDB
|
||||
- `setup_postgresql(VERSION)` - Install PostgreSQL
|
||||
- `setup_postgresql_db()` - Create user/db in PostgreSQL
|
||||
- `setup_mongodb(VERSION)` - Install MongoDB
|
||||
- `setup_redis(VERSION)` - Install Redis cache
|
||||
- `setup_meilisearch()` - Install Meilisearch engine
|
||||
|
||||
**Web Servers**:
|
||||
- `setup_nginx()` - Install Nginx
|
||||
- `setup_apache()` - Install Apache HTTP Server
|
||||
- `setup_caddy()` - Install Caddy
|
||||
- `setup_traefik()` - Install Traefik proxy
|
||||
|
||||
**Containers**:
|
||||
- `setup_docker()` - Install Docker
|
||||
- `setup_podman()` - Install Podman
|
||||
|
||||
**Development**:
|
||||
- `setup_git()` - Install Git
|
||||
- `setup_docker_compose()` - Install Docker Compose
|
||||
- `setup_composer()` - Install PHP Composer
|
||||
- `setup_build_tools()` - Install build-essential
|
||||
- `setup_yq()` - Install mikefarah/yq processor
|
||||
|
||||
**Monitoring**:
|
||||
- `setup_grafana()` - Install Grafana
|
||||
- `setup_prometheus()` - Install Prometheus
|
||||
- `setup_telegraf()` - Install Telegraf
|
||||
|
||||
**System**:
|
||||
- `setup_wireguard()` - Install WireGuard VPN
|
||||
- `setup_netdata()` - Install Netdata monitoring
|
||||
- `setup_tailscale()` - Install Tailscale
|
||||
- (+ more...)
|
||||
|
||||
---
|
||||
|
||||
## Core Functions
|
||||
|
||||
### install_packages_with_retry()
|
||||
|
||||
Install one or more packages safely with automatic retry logic (3 attempts), APT refresh, and lock handling.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
install_packages_with_retry PACKAGE1 [PACKAGE2 ...]
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `PACKAGE1, PACKAGE2, ...` - Package names to install
|
||||
|
||||
**Returns**:
|
||||
- `0` - All packages installed successfully
|
||||
- `1` - Installation failed after all retries
|
||||
|
||||
**Features**:
|
||||
- Automatically sets `DEBIAN_FRONTEND=noninteractive`
|
||||
- Handles DPKG lock errors with `dpkg --configure -a`
|
||||
- Retries on transient network or APT failures
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
install_packages_with_retry curl wget git
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### upgrade_packages_with_retry()
|
||||
|
||||
Upgrades installed packages with the same robust retry logic as the installation helper.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
upgrade_packages_with_retry
|
||||
```
|
||||
|
||||
**Returns**:
|
||||
- `0` - Upgrade successful
|
||||
- `1` - Upgrade failed
|
||||
|
||||
---
|
||||
|
||||
### fetch_and_deploy_gh_release()
|
||||
|
||||
The primary tool for downloading and installing software from GitHub Releases. Supports binaries, tarballs, and Debian packages.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
fetch_and_deploy_gh_release APPREPO TYPE [VERSION] [DEST] [ASSET_PATTERN]
|
||||
```
|
||||
|
||||
**Environment Variables**:
|
||||
- `APPREPO`: GitHub repository (e.g., `owner/repo`)
|
||||
- `TYPE`: Asset type (`binary`, `tarball`, `prebuild`, `singlefile`)
|
||||
- `VERSION`: Specific tag or `latest` (Default: `latest`)
|
||||
- `DEST`: Target directory (Default: `/opt/$APP`)
|
||||
- `ASSET_PATTERN`: Regex or string pattern to match the release asset (Required for `prebuild` and `singlefile`)
|
||||
|
||||
**Supported Operation Modes**:
|
||||
- `tarball`: Downloads and extracts the source tarball.
|
||||
- `binary`: Detects host architecture and installs a `.deb` package using `apt` or `dpkg`.
|
||||
- `prebuild`: Downloads and extracts a pre-built binary archive (supports `.tar.gz`, `.zip`, `.tgz`, `.txz`).
|
||||
- `singlefile`: Downloads a single binary file to the destination.
|
||||
|
||||
**Environment Variables**:
|
||||
- `CLEAN_INSTALL=1`: Removes all contents of the destination directory before extraction.
|
||||
- `DPKG_FORCE_CONFOLD=1`: Forces `dpkg` to keep old config files during package updates.
|
||||
- `SYSTEMD_OFFLINE=1`: Used automatically for `.deb` installs to prevent systemd-tmpfiles failures in unprivileged containers.
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
fetch_and_deploy_gh_release "muesli/duf" "binary" "latest" "/opt/duf" "duf_.*_linux_amd64.tar.gz"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### check_for_gh_release()
|
||||
|
||||
Checks if a newer version is available on GitHub compared to the installed version.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
check_for_gh_release APP REPO
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
if check_for_gh_release "nodejs" "nodesource/distributions"; then
|
||||
# update logic
|
||||
fi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### prepare_repository_setup()
|
||||
|
||||
Performs safe repository preparation by cleaning up old files, keyrings, and ensuring the APT system is in a working state.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
prepare_repository_setup REPO_NAME [REPO_NAME2 ...]
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
prepare_repository_setup "mariadb" "mysql"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### verify_tool_version()
|
||||
|
||||
Validates if the installed major version matches the expected version.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
verify_tool_version NAME EXPECTED INSTALLED
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
verify_tool_version "nodejs" "22" "$(node -v | grep -oP '^v\K[0-9]+')"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### setup_deb822_repo()
|
||||
|
||||
Add repository in modern deb822 format.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
setup_deb822_repo NAME GPG_URL REPO_URL SUITE COMPONENT [ARCHITECTURES] [ENABLED]
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `NAME` - Repository name (e.g., "nodejs")
|
||||
- `GPG_URL` - URL to GPG key (e.g., https://example.com/key.gpg)
|
||||
- `REPO_URL` - Main repository URL (e.g., https://example.com/repo)
|
||||
- `SUITE` - Repository suite (e.g., "jammy", "bookworm")
|
||||
- `COMPONENT` - Repository component (e.g., "main", "testing")
|
||||
- `ARCHITECTURES` - Optional Comma-separated list of architectures (e.g., "amd64,arm64")
|
||||
- `ENABLED` - Optional "true" or "false" (default: "true")
|
||||
|
||||
**Returns**:
|
||||
- `0` - Repository added successfully
|
||||
- `1` - Repository setup failed
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
setup_deb822_repo \
|
||||
"nodejs" \
|
||||
"https://deb.nodesource.com/gpgkey/nodesource.gpg.key" \
|
||||
"https://deb.nodesource.com/node_20.x" \
|
||||
"jammy" \
|
||||
"main"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### cleanup_repo_metadata()
|
||||
|
||||
Clean up GPG keys and old repository configurations.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
cleanup_repo_metadata
|
||||
```
|
||||
|
||||
**Parameters**: None
|
||||
|
||||
**Returns**:
|
||||
- `0` - Cleanup complete
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
cleanup_repo_metadata
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tool Installation Functions
|
||||
|
||||
### setup_nodejs()
|
||||
|
||||
Install Node.js and npm from official repositories. Handles legacy version cleanup (nvm) automatically.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
setup_nodejs
|
||||
```
|
||||
|
||||
**Environment Variables**:
|
||||
- `NODE_VERSION`: Major version to install (e.g. "20", "22", "24"). Default: "24".
|
||||
- `NODE_MODULE`: Optional npm package to install globally during setup (e.g. "pnpm", "yarn").
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
NODE_VERSION="22" NODE_MODULE="pnpm" setup_nodejs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### setup_php()
|
||||
|
||||
Install PHP with configurable extensions and FPM/Apache integration.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
setup_php
|
||||
```
|
||||
|
||||
**Environment Variables**:
|
||||
- `PHP_VERSION`: Version to install (e.g. "8.3", "8.4"). Default: "8.4".
|
||||
- `PHP_MODULE`: Comma-separated list of additional extensions.
|
||||
- `PHP_FPM`: Set to "YES" to install php-fpm.
|
||||
- `PHP_APACHE`: Set to "YES" to install libapache2-mod-php.
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
PHP_VERSION="8.3" PHP_FPM="YES" PHP_MODULE="mysql,xml,zip" setup_php
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### setup_mariadb_db()
|
||||
|
||||
Creates a new MariaDB database and a dedicated user with all privileges. Automatically generates a password if not provided and saves it to a credentials file.
|
||||
|
||||
**Environment Variables**:
|
||||
- `MARIADB_DB_NAME`: Name of the database (required)
|
||||
- `MARIADB_DB_USER`: Name of the database user (required)
|
||||
- `MARIADB_DB_PASS`: User password (optional, auto-generated if omitted)
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
MARIADB_DB_NAME="myapp" MARIADB_DB_USER="myapp_user" setup_mariadb_db
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### setup_postgresql_db()
|
||||
|
||||
Creates a new PostgreSQL database and a dedicated user/role with all privileges. Automatically generates a password if not provided and saves it to a credentials file.
|
||||
|
||||
**Environment Variables**:
|
||||
- `PG_DB_NAME`: Name of the database (required)
|
||||
- `PG_DB_USER`: Name of the database user (required)
|
||||
- `PG_DB_PASS`: User password (optional, auto-generated if omitted)
|
||||
|
||||
---
|
||||
|
||||
### setup_java()
|
||||
|
||||
Installs Temurin JDK.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
JAVA_VERSION="21" setup_java
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `JAVA_VERSION` - JDK version (e.g., "17", "21") (default: "21")
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
JAVA_VERSION="17" setup_java
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### setup_uv()
|
||||
|
||||
Installs `uv` (modern Python package manager).
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
PYTHON_VERSION="3.13" setup_uv
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `PYTHON_VERSION` - Optional Python version to pre-install via uv (e.g., "3.12", "3.13")
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
PYTHON_VERSION="3.13" setup_uv
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### setup_go()
|
||||
|
||||
Installs Go programming language.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
GO_VERSION="1.23" setup_go
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `GO_VERSION` - Go version to install (default: "1.23")
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
GO_VERSION="1.24" setup_go
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### setup_yq()
|
||||
|
||||
Installs `yq` (YAML processor).
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
setup_yq
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
setup_yq
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### setup_composer()
|
||||
|
||||
Installs PHP Composer.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
setup_composer
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
setup_composer
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### setup_meilisearch()
|
||||
|
||||
Install and configure Meilisearch search engine.
|
||||
|
||||
**Environment Variables**:
|
||||
- `MEILISEARCH_BIND`: Address and port to bind to (Default: "127.0.0.1:7700")
|
||||
- `MEILISEARCH_ENV`: Environment mode (Default: "production")
|
||||
|
||||
---
|
||||
|
||||
### setup_yq()
|
||||
|
||||
Install the `mikefarah/yq` YAML processor. Removes existing non-compliant versions.
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
setup_yq
|
||||
yq eval '.app.version = "1.0.0"' -i config.yaml
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### setup_composer()
|
||||
|
||||
Install or update the PHP Composer package manager. Handles `COMPOSER_ALLOW_SUPERUSER` automatically and performs self-updates if already installed.
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
setup_php
|
||||
setup_composer
|
||||
$STD composer install --no-dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### setup_build_tools()
|
||||
|
||||
Install the `build-essential` package suite for compiling software.
|
||||
|
||||
---
|
||||
|
||||
### setup_uv()
|
||||
|
||||
Install the modern Python package manager `uv`. Extremely fast replacement for pip/venv.
|
||||
|
||||
**Environment Variables**:
|
||||
- `PYTHON_VERSION`: Major.Minor version to ensure is installed.
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
PYTHON_VERSION="3.12" setup_uv
|
||||
uv sync --locked
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### setup_java()
|
||||
|
||||
Install OpenJDK via the Adoptium repository.
|
||||
|
||||
**Environment Variables**:
|
||||
- `JAVA_VERSION`: Major version to install (e.g. "17", "21"). Default: "21".
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
JAVA_VERSION="21" setup_java
|
||||
```
|
||||
|
||||
---
|
||||
```bash
|
||||
setup_nodejs VERSION
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `VERSION` - Node.js version (e.g., "20", "22", "lts")
|
||||
|
||||
**Returns**:
|
||||
- `0` - Installation successful
|
||||
- `1` - Installation failed
|
||||
|
||||
**Creates**:
|
||||
- `/opt/nodejs_version.txt` - Version file
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
setup_nodejs "20"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### setup_php(VERSION)
|
||||
|
||||
Install PHP-FPM, CLI, and common extensions.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
setup_php VERSION
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `VERSION` - PHP version (e.g., "8.2", "8.3")
|
||||
|
||||
**Returns**:
|
||||
- `0` - Installation successful
|
||||
- `1` - Installation failed
|
||||
|
||||
**Creates**:
|
||||
- `/opt/php_version.txt` - Version file
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
setup_php "8.3"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### setup_mariadb()
|
||||
|
||||
Install MariaDB server and client utilities.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
setup_mariadb # Uses distribution packages (recommended)
|
||||
MARIADB_VERSION="11.4" setup_mariadb # Uses official MariaDB repository
|
||||
```
|
||||
|
||||
**Variables**:
|
||||
- `MARIADB_VERSION` - (optional) Specific MariaDB version
|
||||
- Not set or `"latest"`: Uses distribution packages (most reliable, avoids mirror issues)
|
||||
- Specific version (e.g., `"11.4"`, `"12.2"`): Uses official MariaDB repository
|
||||
|
||||
**Returns**:
|
||||
- `0` - Installation successful
|
||||
- `1` - Installation failed
|
||||
|
||||
**Creates**:
|
||||
- `/opt/mariadb_version.txt` - Version file
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
# Recommended: Use distribution packages (stable, no mirror issues)
|
||||
setup_mariadb
|
||||
|
||||
# Specific version from official repository
|
||||
MARIADB_VERSION="11.4" setup_mariadb
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### setup_postgresql(VERSION)
|
||||
|
||||
Install PostgreSQL server and client utilities.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
setup_postgresql VERSION
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `VERSION` - PostgreSQL version (e.g., "14", "15", "16")
|
||||
|
||||
**Returns**:
|
||||
- `0` - Installation successful
|
||||
- `1` - Installation failed
|
||||
|
||||
**Creates**:
|
||||
- `/opt/postgresql_version.txt` - Version file
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
setup_postgresql "16"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### setup_docker()
|
||||
|
||||
Install Docker and Docker CLI.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
setup_docker
|
||||
```
|
||||
|
||||
**Parameters**: None
|
||||
|
||||
**Returns**:
|
||||
- `0` - Installation successful
|
||||
- `1` - Installation failed
|
||||
|
||||
**Creates**:
|
||||
- `/opt/docker_version.txt` - Version file
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
setup_docker
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### setup_composer()
|
||||
|
||||
Install PHP Composer (dependency manager).
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
setup_composer
|
||||
```
|
||||
|
||||
**Parameters**: None
|
||||
|
||||
**Returns**:
|
||||
- `0` - Installation successful
|
||||
- `1` - Installation failed
|
||||
|
||||
**Creates**:
|
||||
- `/usr/local/bin/composer` - Composer executable
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
setup_composer
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### setup_build_tools()
|
||||
|
||||
Install build-essential and development tools (gcc, make, etc.).
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
setup_build_tools
|
||||
```
|
||||
|
||||
**Parameters**: None
|
||||
|
||||
**Returns**:
|
||||
- `0` - Installation successful
|
||||
- `1` - Installation failed
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
setup_build_tools
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## System Configuration
|
||||
|
||||
### setting_up_container()
|
||||
|
||||
Display setup message and initialize container environment.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
setting_up_container
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
setting_up_container
|
||||
# Output: ⏳ Setting up container...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### motd_ssh()
|
||||
|
||||
Configure SSH daemon and MOTD for container.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
motd_ssh
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
motd_ssh
|
||||
# Configures SSH and creates MOTD
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### customize()
|
||||
|
||||
Apply container customizations and final setup.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
customize
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
customize
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### cleanup_lxc()
|
||||
|
||||
Final cleanup of temporary files and logs.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
cleanup_lxc
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
cleanup_lxc
|
||||
# Removes temp files, finalizes installation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### Basic Installation Sequence
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
|
||||
|
||||
pkg_update # Update package lists
|
||||
setup_nodejs "20" # Install Node.js
|
||||
setup_mariadb # Install MariaDB (distribution packages)
|
||||
|
||||
# ... application installation ...
|
||||
|
||||
motd_ssh # Setup SSH/MOTD
|
||||
customize # Apply customizations
|
||||
cleanup_lxc # Final cleanup
|
||||
```
|
||||
|
||||
### Tool Chain Installation
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
|
||||
|
||||
# Install full web stack
|
||||
pkg_update
|
||||
setup_nginx
|
||||
setup_php "8.3"
|
||||
setup_mariadb # Uses distribution packages
|
||||
setup_composer
|
||||
```
|
||||
|
||||
### With Repository Setup
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
|
||||
|
||||
pkg_update
|
||||
|
||||
# Add Node.js repository
|
||||
setup_deb822_repo \
|
||||
"https://deb.nodesource.com/gpgkey/nodesource.gpg.key" \
|
||||
"nodejs" \
|
||||
"jammy" \
|
||||
"https://deb.nodesource.com/node_20.x" \
|
||||
"main"
|
||||
|
||||
pkg_update
|
||||
setup_nodejs "20"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: December 2025
|
||||
**Total Functions**: 30+
|
||||
**Maintained by**: community-scripts team
|
||||
@@ -1,418 +0,0 @@
|
||||
# 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
|
||||
@@ -1,420 +0,0 @@
|
||||
# tools.func Usage Examples
|
||||
|
||||
Practical, real-world examples for using tools.func functions in application installation scripts.
|
||||
|
||||
## Basic Examples
|
||||
|
||||
### Example 1: Simple Package Installation
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
|
||||
|
||||
# Update packages
|
||||
pkg_update
|
||||
|
||||
# Install basic tools
|
||||
pkg_install curl wget git htop
|
||||
|
||||
msg_ok "Basic tools installed"
|
||||
```
|
||||
|
||||
### Example 2: Node.js Application
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
|
||||
|
||||
setting_up_container
|
||||
network_check
|
||||
update_os
|
||||
|
||||
msg_info "Installing Node.js"
|
||||
pkg_update
|
||||
setup_nodejs "20"
|
||||
msg_ok "Node.js installed"
|
||||
|
||||
msg_info "Downloading application"
|
||||
cd /opt
|
||||
git clone https://github.com/example/app.git
|
||||
cd app
|
||||
npm install
|
||||
msg_ok "Application installed"
|
||||
|
||||
motd_ssh
|
||||
customize
|
||||
cleanup_lxc
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Examples
|
||||
|
||||
### Example 3: PHP + MySQL Web Application
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
|
||||
|
||||
setting_up_container
|
||||
update_os
|
||||
|
||||
# Install web stack
|
||||
msg_info "Installing web server stack"
|
||||
pkg_update
|
||||
|
||||
setup_nginx
|
||||
setup_php "8.3"
|
||||
setup_mariadb # Uses distribution packages (recommended)
|
||||
setup_composer
|
||||
|
||||
msg_ok "Web stack installed"
|
||||
|
||||
# Download application
|
||||
msg_info "Downloading application"
|
||||
git clone https://github.com/example/php-app /var/www/html/app
|
||||
cd /var/www/html/app
|
||||
|
||||
# Install dependencies
|
||||
composer install --no-dev
|
||||
|
||||
# Setup database
|
||||
msg_info "Setting up database"
|
||||
DBPASS=$(openssl rand -base64 18 | tr -dc 'a-zA-Z0-9' | head -c13)
|
||||
mysql -e "CREATE DATABASE phpapp; GRANT ALL ON phpapp.* TO 'phpapp'@'localhost' IDENTIFIED BY '$DBPASS';"
|
||||
|
||||
# Create .env file
|
||||
cat > .env <<EOF
|
||||
DB_HOST=localhost
|
||||
DB_NAME=phpapp
|
||||
DB_USER=phpapp
|
||||
DB_PASS=$DBPASS
|
||||
APP_ENV=production
|
||||
EOF
|
||||
|
||||
# Fix permissions
|
||||
chown -R www-data:www-data /var/www/html/app
|
||||
chmod -R 755 /var/www/html/app
|
||||
|
||||
msg_ok "PHP application configured"
|
||||
|
||||
motd_ssh
|
||||
customize
|
||||
cleanup_lxc
|
||||
```
|
||||
|
||||
### Example 4: Docker Application
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
|
||||
|
||||
setting_up_container
|
||||
update_os
|
||||
|
||||
msg_info "Installing Docker"
|
||||
setup_docker
|
||||
msg_ok "Docker installed"
|
||||
|
||||
msg_info "Pulling application image"
|
||||
docker pull myregistry.io/myapp:latest
|
||||
msg_ok "Application image ready"
|
||||
|
||||
msg_info "Starting Docker container"
|
||||
docker run -d \
|
||||
--name myapp \
|
||||
--restart unless-stopped \
|
||||
-p 8080:3000 \
|
||||
-e APP_ENV=production \
|
||||
myregistry.io/myapp:latest
|
||||
|
||||
msg_ok "Docker container running"
|
||||
|
||||
# Enable Docker service
|
||||
systemctl enable docker
|
||||
systemctl start docker
|
||||
|
||||
motd_ssh
|
||||
customize
|
||||
cleanup_lxc
|
||||
```
|
||||
|
||||
### Example 5: PostgreSQL + Node.js
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
|
||||
|
||||
setting_up_container
|
||||
update_os
|
||||
|
||||
# Install full stack
|
||||
setup_nodejs "20"
|
||||
setup_postgresql "16"
|
||||
setup_git
|
||||
|
||||
msg_info "Installing application"
|
||||
git clone https://github.com/example/nodejs-app /opt/app
|
||||
cd /opt/app
|
||||
|
||||
npm install
|
||||
npm run build
|
||||
|
||||
# Setup database
|
||||
DBPASS=$(openssl rand -base64 18 | tr -dc 'a-zA-Z0-9' | head -c13)
|
||||
sudo -u postgres psql <<EOF
|
||||
CREATE DATABASE nodeapp;
|
||||
CREATE USER nodeapp WITH PASSWORD '$DBPASS';
|
||||
GRANT ALL PRIVILEGES ON DATABASE nodeapp TO nodeapp;
|
||||
EOF
|
||||
|
||||
# Create environment file
|
||||
cat > .env <<EOF
|
||||
DATABASE_URL=postgresql://nodeapp:$DBPASS@localhost/nodeapp
|
||||
NODE_ENV=production
|
||||
PORT=3000
|
||||
EOF
|
||||
|
||||
# Create systemd service
|
||||
cat > /etc/systemd/system/nodeapp.service <<EOF
|
||||
[Unit]
|
||||
Description=Node.js Application
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=nodeapp
|
||||
WorkingDirectory=/opt/app
|
||||
ExecStart=/usr/bin/node /opt/app/dist/index.js
|
||||
Restart=on-failure
|
||||
RestartSec=5s
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
EOF
|
||||
|
||||
# Create nodeapp user
|
||||
useradd -r -s /bin/bash nodeapp || true
|
||||
chown -R nodeapp:nodeapp /opt/app
|
||||
|
||||
# Start service
|
||||
systemctl daemon-reload
|
||||
systemctl enable nodeapp
|
||||
systemctl start nodeapp
|
||||
|
||||
motd_ssh
|
||||
customize
|
||||
cleanup_lxc
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Repository Configuration Examples
|
||||
|
||||
### Example 6: Adding Custom Repository
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
|
||||
|
||||
msg_info "Setting up repository"
|
||||
|
||||
# Add custom repository in deb822 format
|
||||
setup_deb822_repo \
|
||||
"my-applications" \
|
||||
"https://my-repo.example.com/gpg.key" \
|
||||
"https://my-repo.example.com/debian" \
|
||||
"jammy" \
|
||||
"main"
|
||||
|
||||
msg_ok "Repository configured"
|
||||
|
||||
# Update and install
|
||||
pkg_update
|
||||
pkg_install my-app-package
|
||||
```
|
||||
|
||||
### Example 7: Multiple Repository Setup
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
|
||||
|
||||
msg_info "Setting up repositories"
|
||||
|
||||
# Node.js repository
|
||||
setup_deb822_repo \
|
||||
"nodejs" \
|
||||
"https://deb.nodesource.com/gpgkey/nodesource.gpg.key" \
|
||||
"https://deb.nodesource.com/node_20.x" \
|
||||
"jammy" \
|
||||
"main"
|
||||
|
||||
# Docker repository
|
||||
setup_deb822_repo \
|
||||
"docker" \
|
||||
"https://download.docker.com/linux/ubuntu/gpg" \
|
||||
"https://download.docker.com/linux/ubuntu" \
|
||||
"jammy" \
|
||||
"stable"
|
||||
|
||||
# Update once for all repos
|
||||
pkg_update
|
||||
|
||||
# Install from repos
|
||||
setup_nodejs "20"
|
||||
setup_docker
|
||||
|
||||
msg_ok "All repositories configured"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling Examples
|
||||
|
||||
### Example 8: With Error Handling
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
|
||||
|
||||
catch_errors
|
||||
setting_up_container
|
||||
update_os
|
||||
|
||||
# Install with error checking
|
||||
if ! pkg_update; then
|
||||
msg_error "Failed to update packages"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if ! setup_nodejs "20"; then
|
||||
msg_error "Failed to install Node.js"
|
||||
# Could retry or fallback here
|
||||
exit 1
|
||||
fi
|
||||
|
||||
msg_ok "Installation successful"
|
||||
```
|
||||
|
||||
### Example 9: Conditional Installation
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
|
||||
|
||||
setting_up_container
|
||||
update_os
|
||||
|
||||
# Check if Node.js already installed
|
||||
if command -v node >/dev/null 2>&1; then
|
||||
msg_ok "Node.js already installed: $(node --version)"
|
||||
else
|
||||
msg_info "Installing Node.js"
|
||||
setup_nodejs "20"
|
||||
msg_ok "Node.js installed: $(node --version)"
|
||||
fi
|
||||
|
||||
# Same for other tools
|
||||
if command -v docker >/dev/null 2>&1; then
|
||||
msg_ok "Docker already installed"
|
||||
else
|
||||
msg_info "Installing Docker"
|
||||
setup_docker
|
||||
fi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Production Patterns
|
||||
|
||||
### Example 10: Production Installation Template
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
|
||||
|
||||
# === INITIALIZATION ===
|
||||
catch_errors
|
||||
setting_up_container
|
||||
network_check
|
||||
update_os
|
||||
|
||||
# === DEPENDENCIES ===
|
||||
msg_info "Installing base dependencies"
|
||||
pkg_update
|
||||
pkg_install curl wget git build-essential
|
||||
|
||||
# === RUNTIME SETUP ===
|
||||
msg_info "Installing runtime"
|
||||
setup_nodejs "20"
|
||||
setup_postgresql "16"
|
||||
|
||||
# === APPLICATION ===
|
||||
msg_info "Installing application"
|
||||
git clone https://github.com/user/app /opt/app
|
||||
cd /opt/app
|
||||
npm install --omit=dev
|
||||
npm run build
|
||||
|
||||
# === CONFIGURATION ===
|
||||
msg_info "Configuring application"
|
||||
# ... configuration steps ...
|
||||
|
||||
# === SERVICES ===
|
||||
msg_info "Setting up services"
|
||||
# ... service setup ...
|
||||
|
||||
# === FINALIZATION ===
|
||||
msg_ok "Installation complete"
|
||||
motd_ssh
|
||||
customize
|
||||
cleanup_lxc
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tips & Best Practices
|
||||
|
||||
### ✅ DO
|
||||
```bash
|
||||
# Use $STD for silent operations
|
||||
$STD apt-get install curl
|
||||
|
||||
# Use pkg_update before installing
|
||||
pkg_update
|
||||
pkg_install package-name
|
||||
|
||||
# Chain multiple tools together
|
||||
setup_nodejs "20"
|
||||
setup_php "8.3"
|
||||
setup_mariadb # Distribution packages (recommended)
|
||||
|
||||
# Check command success
|
||||
if ! setup_docker; then
|
||||
msg_error "Docker installation failed"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
### ❌ DON'T
|
||||
```bash
|
||||
# Don't hardcode commands
|
||||
apt-get install curl # Bad
|
||||
|
||||
# Don't skip updates
|
||||
pkg_install package # May fail if cache stale
|
||||
|
||||
# Don't ignore errors
|
||||
setup_nodejs || true # Silences errors silently
|
||||
|
||||
# Don't mix package managers
|
||||
apt-get install curl
|
||||
apk add wget # Don't mix!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: December 2025
|
||||
**Examples**: 10 detailed patterns
|
||||
**All examples tested and verified**
|
||||
Reference in New Issue
Block a user