mirror of
https://github.com/community-scripts/ProxmoxVE.git
synced 2025-12-25 00:16:24 +01:00
add comprehensive documentation (#9537)
This commit is contained in:
CanbiZ
234
docs/misc/tools.func/README.md
Normal file
234
docs/misc/tools.func/README.md
Normal file
@ -0,0 +1,234 @@
|
||||
# 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 "11" # Install MariaDB 11
|
||||
```
|
||||
|
||||
### 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
|
||||
199
docs/misc/tools.func/TOOLS_FUNC_FLOWCHART.md
Normal file
199
docs/misc/tools.func/TOOLS_FUNC_FLOWCHART.md
Normal file
@ -0,0 +1,199 @@
|
||||
# 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
|
||||
491
docs/misc/tools.func/TOOLS_FUNC_FUNCTIONS_REFERENCE.md
Normal file
491
docs/misc/tools.func/TOOLS_FUNC_FUNCTIONS_REFERENCE.md
Normal file
@ -0,0 +1,491 @@
|
||||
# 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_ruby(VERSION)` - Install Ruby with gem
|
||||
- `setup_golang(VERSION)` - Install Go programming language
|
||||
|
||||
**Databases**:
|
||||
- `setup_mariadb(VERSION)` - Install MariaDB server
|
||||
- `setup_postgresql(VERSION)` - Install PostgreSQL
|
||||
- `setup_mongodb(VERSION)` - Install MongoDB
|
||||
- `setup_redis(VERSION)` - Install Redis cache
|
||||
|
||||
**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
|
||||
|
||||
**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
|
||||
|
||||
### pkg_install()
|
||||
|
||||
Install one or more packages safely with automatic retry logic and error handling.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
pkg_install PACKAGE1 [PACKAGE2 ...]
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `PACKAGE1, PACKAGE2, ...` - Package names to install
|
||||
|
||||
**Returns**:
|
||||
- `0` - All packages installed successfully
|
||||
- `1` - Installation failed after retries
|
||||
|
||||
**Environment Variables**:
|
||||
- `$STD` - Output suppression (`silent` or empty)
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
pkg_install curl wget git
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### pkg_update()
|
||||
|
||||
Update package lists with automatic retry logic for network failures.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
pkg_update
|
||||
```
|
||||
|
||||
**Parameters**: None
|
||||
|
||||
**Returns**:
|
||||
- `0` - Package lists updated
|
||||
- `1` - Failed after 3 retries
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
pkg_update
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### pkg_remove()
|
||||
|
||||
Remove packages completely including dependencies.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
pkg_remove PACKAGE1 [PACKAGE2 ...]
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `PACKAGE1, PACKAGE2, ...` - Package names to remove
|
||||
|
||||
**Returns**:
|
||||
- `0` - Packages removed
|
||||
- `1` - Removal failed
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
pkg_remove old-package outdated-tool
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### setup_deb822_repo()
|
||||
|
||||
Add repository in modern deb822 format (recommended over legacy format).
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
setup_deb822_repo REPO_URL NAME DIST MAIN_URL RELEASE
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `REPO_URL` - URL to GPG key (e.g., https://example.com/key.gpg)
|
||||
- `NAME` - Repository name (e.g., "nodejs")
|
||||
- `DIST` - Distribution (jammy, bookworm, etc.)
|
||||
- `MAIN_URL` - Main repository URL
|
||||
- `RELEASE` - Release type (main, testing, etc.)
|
||||
|
||||
**Returns**:
|
||||
- `0` - Repository added successfully
|
||||
- `1` - Repository setup failed
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
setup_deb822_repo \
|
||||
"https://deb.nodesource.com/gpgkey/nodesource.gpg.key" \
|
||||
"nodejs" \
|
||||
"jammy" \
|
||||
"https://deb.nodesource.com/node_20.x" \
|
||||
"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(VERSION)
|
||||
|
||||
Install Node.js and npm from official repositories.
|
||||
|
||||
**Signature**:
|
||||
```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(VERSION)
|
||||
|
||||
Install MariaDB server and client utilities.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
setup_mariadb VERSION
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `VERSION` - MariaDB version (e.g., "10.6", "11.0")
|
||||
|
||||
**Returns**:
|
||||
- `0` - Installation successful
|
||||
- `1` - Installation failed
|
||||
|
||||
**Creates**:
|
||||
- `/opt/mariadb_version.txt` - Version file
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
setup_mariadb "11.0"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 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 "11" # Install MariaDB
|
||||
|
||||
# ... 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 "11"
|
||||
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
|
||||
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
|
||||
420
docs/misc/tools.func/TOOLS_FUNC_USAGE_EXAMPLES.md
Normal file
420
docs/misc/tools.func/TOOLS_FUNC_USAGE_EXAMPLES.md
Normal file
@ -0,0 +1,420 @@
|
||||
# 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 "11"
|
||||
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 \
|
||||
"https://my-repo.example.com/gpg.key" \
|
||||
"my-applications" \
|
||||
"jammy" \
|
||||
"https://my-repo.example.com/debian" \
|
||||
"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 \
|
||||
"https://deb.nodesource.com/gpgkey/nodesource.gpg.key" \
|
||||
"nodejs" \
|
||||
"jammy" \
|
||||
"https://deb.nodesource.com/node_20.x" \
|
||||
"main"
|
||||
|
||||
# Docker repository
|
||||
setup_deb822_repo \
|
||||
"https://download.docker.com/linux/ubuntu/gpg" \
|
||||
"docker" \
|
||||
"jammy" \
|
||||
"https://download.docker.com/linux/ubuntu" \
|
||||
"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 "11"
|
||||
|
||||
# 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