mirror of
https://github.com/community-scripts/ProxmoxVED.git
synced 2026-02-25 05:57:26 +00:00
Add comprehensive documentation for all project sections
Introduced new and updated documentation files across the docs/ directory, including project structure guides, function library references, and standardized READMEs for ct, install, vm, tools, api, and misc. This update fully documents all nine function libraries, provides quick start and learning paths, and mirrors the project structure for easier navigation and contribution.
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 ProxmoxVED ecosystem.
|
||||
|
||||
## Component Relationships
|
||||
|
||||
### tools.func in the Installation Pipeline
|
||||
|
||||
```
|
||||
ct/AppName.sh (host)
|
||||
│
|
||||
├─ Calls build.func
|
||||
│
|
||||
└─ Creates Container
|
||||
│
|
||||
▼
|
||||
install/appname-install.sh (container)
|
||||
│
|
||||
├─ Sources: core.func (colors, messaging)
|
||||
├─ Sources: error_handler.func (error handling)
|
||||
├─ Sources: install.func (container setup)
|
||||
│
|
||||
└─ ★ Sources: tools.func ★
|
||||
│
|
||||
├─ pkg_update()
|
||||
├─ pkg_install()
|
||||
├─ setup_nodejs()
|
||||
├─ setup_php()
|
||||
├─ setup_mariadb()
|
||||
└─ ... 30+ functions
|
||||
```
|
||||
|
||||
### Integration with core.func
|
||||
|
||||
**tools.func uses core.func for**:
|
||||
- `msg_info()` - Display progress messages
|
||||
- `msg_ok()` - Display success messages
|
||||
- `msg_error()` - Display error messages
|
||||
- `msg_warn()` - Display warnings
|
||||
- Color codes (GN, RD, YW, BL) for formatted output
|
||||
- `$STD` variable - Output suppression control
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
# tools.func internally calls:
|
||||
msg_info "Installing Node.js" # Uses core.func
|
||||
setup_nodejs "20" # Setup happens
|
||||
msg_ok "Node.js installed" # Uses core.func
|
||||
```
|
||||
|
||||
### Integration with error_handler.func
|
||||
|
||||
**tools.func uses error_handler.func for**:
|
||||
- Exit code mapping to error descriptions
|
||||
- Automatic error trapping (catch_errors)
|
||||
- Signal handlers (SIGINT, SIGTERM, EXIT)
|
||||
- Structured error reporting
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
# If setup_nodejs fails, error_handler catches it:
|
||||
catch_errors # Calls from error_handler.func
|
||||
setup_nodejs "20" # If this exits non-zero
|
||||
# error_handler logs and traps it
|
||||
```
|
||||
|
||||
### Integration with install.func
|
||||
|
||||
**tools.func coordinates with install.func for**:
|
||||
- Initial OS updates (install.func) → then tools (tools.func)
|
||||
- Network verification before tool installation
|
||||
- Package manager state validation
|
||||
- Cleanup procedures after tool setup
|
||||
|
||||
**Sequence**:
|
||||
```bash
|
||||
setting_up_container() # From install.func
|
||||
network_check() # From install.func
|
||||
update_os() # From install.func
|
||||
|
||||
pkg_update # From tools.func
|
||||
setup_nodejs() # From tools.func
|
||||
|
||||
motd_ssh() # From install.func
|
||||
customize() # From install.func
|
||||
cleanup_lxc() # From install.func
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with alpine-tools.func (Alpine Containers)
|
||||
|
||||
### When to Use tools.func vs alpine-tools.func
|
||||
|
||||
| Feature | tools.func (Debian) | alpine-tools.func (Alpine) |
|
||||
|---------|:---:|:---:|
|
||||
| Package Manager | apt-get | apk |
|
||||
| Installation Scripts | install/*.sh | install/*-alpine.sh |
|
||||
| Tool Setup | `setup_nodejs()` (apt) | `setup_nodejs()` (apk) |
|
||||
| Repository | `setup_deb822_repo()` | `add_community_repo()` |
|
||||
| Services | systemctl | rc-service |
|
||||
|
||||
### Automatic Selection
|
||||
|
||||
Installation scripts detect OS and source appropriate functions:
|
||||
|
||||
```bash
|
||||
# install/myapp-install.sh
|
||||
if grep -qi 'alpine' /etc/os-release; then
|
||||
# Alpine detected - uses alpine-tools.func
|
||||
apk_update
|
||||
apk_add package
|
||||
else
|
||||
# Debian detected - uses tools.func
|
||||
pkg_update
|
||||
pkg_install package
|
||||
fi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dependencies Management
|
||||
|
||||
### External Dependencies
|
||||
|
||||
```
|
||||
tools.func requires:
|
||||
├─ curl (for HTTP requests, GPG keys)
|
||||
├─ wget (for downloads)
|
||||
├─ apt-get (package manager)
|
||||
├─ gpg (GPG key management)
|
||||
├─ openssl (for encryption)
|
||||
└─ systemctl (service management on Debian)
|
||||
```
|
||||
|
||||
### Internal Function Dependencies
|
||||
|
||||
```
|
||||
setup_nodejs()
|
||||
├─ Calls: setup_deb822_repo()
|
||||
├─ Calls: pkg_update()
|
||||
├─ Calls: pkg_install()
|
||||
└─ Uses: msg_info(), msg_ok() [from core.func]
|
||||
|
||||
setup_mariadb()
|
||||
├─ Calls: setup_deb822_repo()
|
||||
├─ Calls: pkg_update()
|
||||
├─ Calls: pkg_install()
|
||||
└─ Uses: msg_info(), msg_ok()
|
||||
|
||||
setup_docker()
|
||||
├─ Calls: cleanup_repo_metadata()
|
||||
├─ Calls: setup_deb822_repo()
|
||||
├─ Calls: pkg_update()
|
||||
└─ Uses: msg_info(), msg_ok()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Function Call Graph
|
||||
|
||||
### Complete Installation Dependency Tree
|
||||
|
||||
```
|
||||
install/app-install.sh
|
||||
│
|
||||
├─ setting_up_container() [install.func]
|
||||
│
|
||||
├─ network_check() [install.func]
|
||||
│
|
||||
├─ update_os() [install.func]
|
||||
│
|
||||
├─ pkg_update() [tools.func]
|
||||
│ └─ Calls: apt-get update (with retry)
|
||||
│
|
||||
├─ setup_nodejs("20") [tools.func]
|
||||
│ ├─ setup_deb822_repo() [tools.func]
|
||||
│ │ └─ Calls: apt-get update
|
||||
│ ├─ pkg_update() [tools.func]
|
||||
│ └─ pkg_install() [tools.func]
|
||||
│
|
||||
├─ setup_php("8.3") [tools.func]
|
||||
│ └─ Similar to setup_nodejs
|
||||
│
|
||||
├─ setup_mariadb("11") [tools.func]
|
||||
│ └─ Similar to setup_nodejs
|
||||
│
|
||||
├─ motd_ssh() [install.func]
|
||||
│
|
||||
├─ customize() [install.func]
|
||||
│
|
||||
└─ cleanup_lxc() [install.func]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration Management
|
||||
|
||||
### Environment Variables Used by tools.func
|
||||
|
||||
```bash
|
||||
# Output control
|
||||
STD="silent" # Suppress apt/apk output
|
||||
VERBOSE="yes" # Show all output
|
||||
|
||||
# Package management
|
||||
DEBIAN_FRONTEND="noninteractive"
|
||||
|
||||
# Tool versions (optional)
|
||||
NODEJS_VERSION="20"
|
||||
PHP_VERSION="8.3"
|
||||
POSTGRES_VERSION="16"
|
||||
```
|
||||
|
||||
### Tools Configuration Files Created
|
||||
|
||||
```
|
||||
/opt/
|
||||
├─ nodejs_version.txt # Node.js version
|
||||
├─ php_version.txt # PHP version
|
||||
├─ mariadb_version.txt # MariaDB version
|
||||
├─ postgresql_version.txt # PostgreSQL version
|
||||
├─ docker_version.txt # Docker version
|
||||
└─ [TOOL]_version.txt # For all installed tools
|
||||
|
||||
/etc/apt/sources.list.d/
|
||||
├─ nodejs.sources # Node.js repo (deb822)
|
||||
├─ docker.sources # Docker repo (deb822)
|
||||
└─ [name].sources # Other repos (deb822)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling Integration
|
||||
|
||||
### Exit Codes from tools.func
|
||||
|
||||
| Code | Meaning | Handled By |
|
||||
|------|:---:|:---:|
|
||||
| 0 | Success | Normal flow |
|
||||
| 1 | Package installation failed | error_handler.func |
|
||||
| 100-101 | APT error | error_handler.func |
|
||||
| 127 | Command not found | error_handler.func |
|
||||
|
||||
### Automatic Cleanup on Failure
|
||||
|
||||
```bash
|
||||
# If any step fails in install script:
|
||||
catch_errors
|
||||
pkg_update # Fail here?
|
||||
setup_nodejs # Doesn't get here
|
||||
|
||||
# error_handler automatically:
|
||||
├─ Logs error
|
||||
├─ Captures exit code
|
||||
├─ Calls cleanup_lxc()
|
||||
└─ Exits with proper code
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with build.func
|
||||
|
||||
### Variable Flow
|
||||
|
||||
```
|
||||
ct/app.sh
|
||||
│
|
||||
├─ var_cpu="2"
|
||||
├─ var_ram="2048"
|
||||
├─ var_disk="10"
|
||||
│
|
||||
└─ Calls: build_container() [build.func]
|
||||
│
|
||||
└─ Creates container
|
||||
│
|
||||
└─ Calls: install/app-install.sh
|
||||
│
|
||||
└─ Uses: tools.func for installation
|
||||
```
|
||||
|
||||
### Resource Considerations
|
||||
|
||||
tools.func respects container resource limits:
|
||||
- Large package installations respect allocated RAM
|
||||
- Database setups use allocated disk space
|
||||
- Build tools (gcc, make) stay within CPU allocation
|
||||
|
||||
---
|
||||
|
||||
## Version Management
|
||||
|
||||
### How tools.func Tracks Versions
|
||||
|
||||
Each tool installation creates a version file:
|
||||
|
||||
```bash
|
||||
# setup_nodejs() creates:
|
||||
echo "20.10.5" > /opt/nodejs_version.txt
|
||||
|
||||
# Used by update scripts:
|
||||
CURRENT=$(cat /opt/nodejs_version.txt)
|
||||
LATEST=$(curl ... # fetch latest)
|
||||
if [[ "$LATEST" != "$CURRENT" ]]; then
|
||||
# Update needed
|
||||
fi
|
||||
```
|
||||
|
||||
### Integration with Update Functions
|
||||
|
||||
```bash
|
||||
# In ct/app.sh:
|
||||
function update_script() {
|
||||
# Check Node version
|
||||
RELEASE=$(curl ... | jq '.version')
|
||||
CURRENT=$(cat /opt/nodejs_version.txt)
|
||||
|
||||
if [[ "$RELEASE" != "$CURRENT" ]]; then
|
||||
# Use tools.func to upgrade
|
||||
setup_nodejs "$RELEASE"
|
||||
fi
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices for Integration
|
||||
|
||||
### ✅ DO
|
||||
|
||||
1. **Call functions in proper order**
|
||||
```bash
|
||||
pkg_update
|
||||
setup_tool "version"
|
||||
```
|
||||
|
||||
2. **Use $STD for production**
|
||||
```bash
|
||||
export STD="silent"
|
||||
pkg_install curl wget
|
||||
```
|
||||
|
||||
3. **Check for existing installations**
|
||||
```bash
|
||||
command -v nodejs >/dev/null || setup_nodejs "20"
|
||||
```
|
||||
|
||||
4. **Coordinate with install.func**
|
||||
```bash
|
||||
setting_up_container
|
||||
update_os # From install.func
|
||||
setup_nodejs # From tools.func
|
||||
motd_ssh # Back to install.func
|
||||
```
|
||||
|
||||
### ❌ DON'T
|
||||
|
||||
1. **Don't skip pkg_update**
|
||||
```bash
|
||||
# Bad - may fail due to stale cache
|
||||
pkg_install curl
|
||||
```
|
||||
|
||||
2. **Don't hardcode versions**
|
||||
```bash
|
||||
# Bad
|
||||
apt-get install nodejs=20.x
|
||||
|
||||
# Good
|
||||
setup_nodejs "20"
|
||||
```
|
||||
|
||||
3. **Don't mix package managers**
|
||||
```bash
|
||||
# Bad
|
||||
apt-get install curl
|
||||
apk add wget
|
||||
```
|
||||
|
||||
4. **Don't ignore errors**
|
||||
```bash
|
||||
# Bad
|
||||
setup_docker || true
|
||||
|
||||
# Good
|
||||
if ! setup_docker; then
|
||||
msg_error "Docker failed"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Integration Issues
|
||||
|
||||
### "Package installation fails"
|
||||
- Check: `pkg_update` was called first
|
||||
- Check: Package name is correct for OS
|
||||
- Solution: Manually verify in container
|
||||
|
||||
### "Tool not accessible after installation"
|
||||
- Check: Tool added to PATH
|
||||
- Check: Version file created
|
||||
- Solution: `which toolname` to verify
|
||||
|
||||
### "Repository conflicts"
|
||||
- Check: No duplicate repositories
|
||||
- Solution: `cleanup_repo_metadata()` before adding
|
||||
|
||||
### "Alpine-specific errors when using Debian tools"
|
||||
- Problem: Using tools.func functions on Alpine
|
||||
- Solution: Use alpine-tools.func instead
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: December 2025
|
||||
**Maintainers**: community-scripts team
|
||||
**Integration Status**: All components fully integrated
|
||||
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