community-scripts/ProxmoxVED
1
0
Fork 0
mirror of https://github.com/community-scripts/ProxmoxVED.git synced 2026-02-24 21:47:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add docs for all files in /misc

Browse Source
This commit is contained in:
Michel Roegl-Brunner
2025-10-10 11:18:59 +02:00
parent b006c4f74b
commit 960fddb9ee
19 changed files with 7095 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

410
docs/misc/build.func/BUILD_FUNC_ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,410 @@
# build.func Architecture Guide
## Overview
This document provides a high-level architectural overview of `build.func`, including module dependencies, data flow, integration points, and system architecture.
## High-Level Architecture
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Proxmox Host System │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ build.func │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────────┐ │ │
│ │ │ Entry Point │ │ Configuration │ │ Container Creation │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ • start() │ │ • variables() │ │ • build_container() │ │ │
│ │ │ • install_ │ │ • base_ │ │ • create_lxc_container() │ │ │
│ │ │ script() │ │ settings() │ │ • configure_gpu_ │ │ │
│ │ │ • advanced_ │ │ • select_ │ │ passthrough() │ │ │
│ │ │ settings() │ │ storage() │ │ • fix_gpu_gids() │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ Module Dependencies │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────────┐ │ │
│ │ │ core.func │ │ error_handler. │ │ api.func │ │ │
│ │ │ │ │ func │ │ │ │ │
│ │ │ • Basic │ │ • Error │ │ • Proxmox API │ │ │
│ │ │ utilities │ │ handling │ │ interactions │ │ │
│ │ │ • Common │ │ • Error │ │ • Container │ │ │
│ │ │ functions │ │ recovery │ │ management │ │ │
│ │ │ • System │ │ • Cleanup │ │ • Status │ │ │
│ │ │ utilities │ │ functions │ │ monitoring │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ tools.func │ │ │
│ │ │ │ │ │
│ │ │ • Additional utilities │ │ │
│ │ │ • Helper functions │ │ │
│ │ │ • System tools │ │ │
│ │ └─────────────────────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
```
## Module Dependencies
### Core Dependencies
```
build.func Dependencies:
├── core.func
│ ├── Basic system utilities
│ ├── Common functions
│ ├── System information
│ └── File operations
├── error_handler.func
│ ├── Error handling
│ ├── Error recovery
│ ├── Cleanup functions
│ └── Error logging
├── api.func
│ ├── Proxmox API interactions
│ ├── Container management
│ ├── Status monitoring
│ └── Configuration updates
└── tools.func
├── Additional utilities
├── Helper functions
├── System tools
└── Custom functions
```
### Dependency Flow
```
Dependency Flow:
├── build.func
│ ├── Sources core.func
│ ├── Sources error_handler.func
│ ├── Sources api.func
│ └── Sources tools.func
├── core.func
│ ├── Basic utilities
│ └── System functions
├── error_handler.func
│ ├── Error management
│ └── Recovery functions
├── api.func
│ ├── Proxmox integration
│ └── Container operations
└── tools.func
├── Additional tools
└── Helper functions
```
## Data Flow Architecture
### Configuration Data Flow
```
Configuration Data Flow:
├── Environment Variables
│ ├── Hard environment variables
│ ├── App-specific .vars
│ ├── Global default.vars
│ └── Built-in defaults
├── Variable Resolution
│ ├── Apply precedence chain
│ ├── Validate settings
│ └── Resolve conflicts
├── Configuration Storage
│ ├── Memory variables
│ ├── Temporary files
│ └── Persistent storage
└── Configuration Usage
├── Container creation
├── Feature configuration
└── Settings persistence
```
### Container Data Flow
```
Container Data Flow:
├── Input Data
│ ├── Configuration variables
│ ├── Resource specifications
│ ├── Network settings
│ └── Storage requirements
├── Processing
│ ├── Validation
│ ├── Conflict resolution
│ ├── Resource allocation
│ └── Configuration generation
├── Container Creation
│ ├── LXC container creation
│ ├── Network configuration
│ ├── Storage setup
│ └── Feature configuration
└── Output
├── Container status
├── Access information
├── Configuration files
└── Log files
```
## Integration Architecture
### With Proxmox System
```
Proxmox Integration:
├── Proxmox Host
│ ├── LXC container management
│ ├── Storage management
│ ├── Network management
│ └── Resource management
├── Proxmox API
│ ├── Container operations
│ ├── Configuration updates
│ ├── Status monitoring
│ └── Error handling
├── Proxmox Configuration
│ ├── /etc/pve/lxc/<ctid>.conf
│ ├── Storage configuration
│ ├── Network configuration
│ └── Resource configuration
└── Proxmox Services
├── Container services
├── Network services
├── Storage services
└── Monitoring services
```
### With Install Scripts
```
Install Script Integration:
├── build.func
│ ├── Creates container
│ ├── Configures basic settings
│ ├── Starts container
│ └── Provides access
├── Install Scripts
│ ├── <app>-install.sh
│ ├── Downloads application
│ ├── Configures application
│ └── Sets up services
├── Container
│ ├── Running application
│ ├── Configured services
│ ├── Network access
│ └── Storage access
└── Integration Points
├── Container creation
├── Network configuration
├── Storage setup
└── Service configuration
```
## System Architecture Components
### Core Components
```
System Components:
├── Entry Point
│ ├── start() function
│ ├── Context detection
│ ├── Environment capture
│ └── Workflow routing
├── Configuration Management
│ ├── Variable resolution
│ ├── Settings persistence
│ ├── Default management
│ └── Validation
├── Container Creation
│ ├── LXC container creation
│ ├── Network configuration
│ ├── Storage setup
│ └── Feature configuration
├── Hardware Integration
│ ├── GPU passthrough
│ ├── USB passthrough
│ ├── Storage management
│ └── Network management
└── Error Handling
├── Error detection
├── Error recovery
├── Cleanup functions
└── User notification
```
### User Interface Components
```
UI Components:
├── Menu System
│ ├── Installation mode selection
│ ├── Configuration menus
│ ├── Storage selection
│ └── GPU configuration
├── Interactive Elements
│ ├── Whiptail menus
│ ├── User prompts
│ ├── Confirmation dialogs
│ └── Error messages
├── Non-Interactive Mode
│ ├── Environment variable driven
│ ├── Silent execution
│ ├── Automated configuration
│ └── Error handling
└── Output
├── Status messages
├── Progress indicators
├── Completion information
└── Access details
```
## Security Architecture
### Security Considerations
```
Security Architecture:
├── Container Security
│ ├── Unprivileged containers (default)
│ ├── Privileged containers (when needed)
│ ├── Resource limits
│ └── Access controls
├── Network Security
│ ├── Network isolation
│ ├── VLAN support
│ ├── Firewall integration
│ └── Access controls
├── Storage Security
│ ├── Storage isolation
│ ├── Access controls
│ ├── Encryption support
│ └── Backup integration
├── GPU Security
│ ├── Device isolation
│ ├── Permission management
│ ├── Access controls
│ └── Security validation
└── API Security
├── Authentication
├── Authorization
├── Input validation
└── Error handling
```
## Performance Architecture
### Performance Considerations
```
Performance Architecture:
├── Execution Optimization
│ ├── Parallel operations
│ ├── Efficient algorithms
│ ├── Minimal user interaction
│ └── Optimized validation
├── Resource Management
│ ├── Memory efficiency
│ ├── CPU optimization
│ ├── Disk usage optimization
│ └── Network efficiency
├── Caching
│ ├── Configuration caching
│ ├── Template caching
│ ├── Storage caching
│ └── GPU detection caching
└── Monitoring
├── Performance monitoring
├── Resource monitoring
├── Error monitoring
└── Status monitoring
```
## Deployment Architecture
### Deployment Scenarios
```
Deployment Scenarios:
├── Single Container
│ ├── Individual application
│ ├── Standard configuration
│ ├── Basic networking
│ └── Standard storage
├── Multiple Containers
│ ├── Application stack
│ ├── Shared networking
│ ├── Shared storage
│ └── Coordinated deployment
├── High Availability
│ ├── Redundant containers
│ ├── Load balancing
│ ├── Failover support
│ └── Monitoring integration
└── Development Environment
├── Development containers
├── Testing containers
├── Staging containers
└── Production containers
```
## Maintenance Architecture
### Maintenance Components
```
Maintenance Architecture:
├── Updates
│ ├── Container updates
│ ├── Application updates
│ ├── Configuration updates
│ └── Security updates
├── Monitoring
│ ├── Container monitoring
│ ├── Resource monitoring
│ ├── Performance monitoring
│ └── Error monitoring
├── Backup
│ ├── Configuration backup
│ ├── Container backup
│ ├── Storage backup
│ └── Recovery procedures
└── Troubleshooting
├── Error diagnosis
├── Log analysis
├── Performance analysis
└── Recovery procedures
```
## Future Architecture Considerations
### Scalability
```
Scalability Considerations:
├── Horizontal Scaling
│ ├── Multiple containers
│ ├── Load balancing
│ ├── Distributed deployment
│ └── Resource distribution
├── Vertical Scaling
│ ├── Resource scaling
│ ├── Performance optimization
│ ├── Capacity planning
│ └── Resource management
├── Automation
│ ├── Automated deployment
│ ├── Automated scaling
│ ├── Automated monitoring
│ └── Automated recovery
└── Integration
├── External systems
├── Cloud integration
├── Container orchestration
└── Service mesh
```

248
docs/misc/build.func/BUILD_FUNC_ENVIRONMENT_VARIABLES.md Normal file
View File

@@ -0,0 +1,248 @@
# build.func Environment Variables Reference
## Overview
This document provides a comprehensive reference of all environment variables used in `build.func`, organized by category and usage context.
## Variable Categories
### Core Container Variables
| Variable | Description | Default | Set In | Used In |
|----------|-------------|---------|---------|---------|
| `APP` | Application name (e.g., "plex", "nextcloud") | - | Environment | Throughout |
| `NSAPP` | Namespace application name | `$APP` | Environment | Throughout |
| `CTID` | Container ID | - | Environment | Container creation |
| `CT_TYPE` | Container type ("install" or "update") | "install" | Environment | Entry point |
| `CT_NAME` | Container name | `$APP` | Environment | Container creation |
### Operating System Variables
| Variable | Description | Default | Set In | Used In |
|----------|-------------|---------|---------|---------|
| `var_os` | Operating system selection | "debian" | base_settings() | OS selection |
| `var_version` | OS version | "12" | base_settings() | Template selection |
| `var_template` | Template name | Auto-generated | base_settings() | Template download |
### Resource Configuration Variables
| Variable | Description | Default | Set In | Used In |
|----------|-------------|---------|---------|---------|
| `var_cpu` | CPU cores | "2" | base_settings() | Container creation |
| `var_ram` | RAM in MB | "2048" | base_settings() | Container creation |
| `var_disk` | Disk size in GB | "8" | base_settings() | Container creation |
| `DISK_SIZE` | Disk size (alternative) | `$var_disk` | Environment | Container creation |
| `CORE_COUNT` | CPU cores (alternative) | `$var_cpu` | Environment | Container creation |
| `RAM_SIZE` | RAM size (alternative) | `$var_ram` | Environment | Container creation |
### Network Configuration Variables
| Variable | Description | Default | Set In | Used In |
|----------|-------------|---------|---------|---------|
| `var_net` | Network interface | "vmbr0" | base_settings() | Network config |
| `var_bridge` | Bridge interface | "vmbr0" | base_settings() | Network config |
| `var_gateway` | Gateway IP | "192.168.1.1" | base_settings() | Network config |
| `var_ip` | Container IP address | - | User input | Network config |
| `var_ipv6` | IPv6 address | - | User input | Network config |
| `var_vlan` | VLAN ID | - | User input | Network config |
| `var_mtu` | MTU size | "1500" | base_settings() | Network config |
| `var_mac` | MAC address | Auto-generated | base_settings() | Network config |
| `NET` | Network interface (alternative) | `$var_net` | Environment | Network config |
| `BRG` | Bridge interface (alternative) | `$var_bridge` | Environment | Network config |
| `GATE` | Gateway IP (alternative) | `$var_gateway` | Environment | Network config |
| `IPV6_METHOD` | IPv6 configuration method | "none" | Environment | Network config |
| `VLAN` | VLAN ID (alternative) | `$var_vlan` | Environment | Network config |
| `MTU` | MTU size (alternative) | `$var_mtu` | Environment | Network config |
| `MAC` | MAC address (alternative) | `$var_mac` | Environment | Network config |
### Storage Configuration Variables
| Variable | Description | Default | Set In | Used In |
|----------|-------------|---------|---------|---------|
| `var_template_storage` | Storage for templates | - | select_storage() | Template storage |
| `var_container_storage` | Storage for container disks | - | select_storage() | Container storage |
| `TEMPLATE_STORAGE` | Template storage (alternative) | `$var_template_storage` | Environment | Template storage |
| `CONTAINER_STORAGE` | Container storage (alternative) | `$var_container_storage` | Environment | Container storage |
### Feature Flags
| Variable | Description | Default | Set In | Used In |
|----------|-------------|---------|---------|---------|
| `ENABLE_FUSE` | Enable FUSE support | "true" | base_settings() | Container features |
| `ENABLE_TUN` | Enable TUN/TAP support | "true" | base_settings() | Container features |
| `ENABLE_KEYCTL` | Enable keyctl support | "true" | base_settings() | Container features |
| `ENABLE_MOUNT` | Enable mount support | "true" | base_settings() | Container features |
| `ENABLE_NESTING` | Enable nesting support | "false" | base_settings() | Container features |
| `ENABLE_PRIVILEGED` | Enable privileged mode | "false" | base_settings() | Container features |
| `ENABLE_UNPRIVILEGED` | Enable unprivileged mode | "true" | base_settings() | Container features |
| `VERBOSE` | Enable verbose output | "false" | Environment | Logging |
| `SSH` | Enable SSH key provisioning | "true" | base_settings() | SSH setup |
### GPU Passthrough Variables
| Variable | Description | Default | Set In | Used In |
|----------|-------------|---------|---------|---------|
| `GPU_APPS` | List of apps that support GPU | - | Environment | GPU detection |
| `var_gpu` | GPU selection | - | User input | GPU passthrough |
| `var_gpu_type` | GPU type (intel/amd/nvidia) | - | detect_gpu_devices() | GPU passthrough |
| `var_gpu_devices` | GPU device list | - | detect_gpu_devices() | GPU passthrough |
### API and Diagnostics Variables
| Variable | Description | Default | Set In | Used In |
|----------|-------------|---------|---------|---------|
| `DIAGNOSTICS` | Enable diagnostics mode | "false" | Environment | Diagnostics |
| `METHOD` | Installation method | "install" | Environment | Installation flow |
| `RANDOM_UUID` | Random UUID for tracking | - | Environment | Logging |
| `API_TOKEN` | Proxmox API token | - | Environment | API calls |
| `API_USER` | Proxmox API user | - | Environment | API calls |
### Settings Persistence Variables
| Variable | Description | Default | Set In | Used In |
|----------|-------------|---------|---------|---------|
| `SAVE_DEFAULTS` | Save settings as defaults | "false" | User input | Settings persistence |
| `SAVE_APP_DEFAULTS` | Save app-specific defaults | "false" | User input | Settings persistence |
| `DEFAULT_VARS_FILE` | Path to default.vars | "/usr/local/community-scripts/default.vars" | Environment | Settings persistence |
| `APP_DEFAULTS_FILE` | Path to app.vars | "/usr/local/community-scripts/defaults/$APP.vars" | Environment | Settings persistence |
## Variable Precedence Chain
Variables are resolved in the following order (highest to lowest priority):
1. **Hard Environment Variables**: Set before script execution
2. **App-specific .vars file**: `/usr/local/community-scripts/defaults/<app>.vars`
3. **Global default.vars file**: `/usr/local/community-scripts/default.vars`
4. **Built-in defaults**: Set in `base_settings()` function
## Critical Variables for Non-Interactive Use
For silent/non-interactive execution, these variables must be set:
```bash
# Core container settings
export APP="plex"
export CTID="100"
export var_hostname="plex-server"
# OS selection
export var_os="debian"
export var_version="12"
# Resource allocation
export var_cpu="4"
export var_ram="4096"
export var_disk="20"
# Network configuration
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.100"
# Storage selection
export var_template_storage="local"
export var_container_storage="local"
# Feature flags
export ENABLE_FUSE="true"
export ENABLE_TUN="true"
export SSH="true"
```
## Environment Variable Usage Patterns
### 1. Container Creation
```bash
# Basic container creation
export APP="nextcloud"
export CTID="101"
export var_hostname="nextcloud-server"
export var_os="debian"
export var_version="12"
export var_cpu="2"
export var_ram="2048"
export var_disk="10"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.101"
export var_template_storage="local"
export var_container_storage="local"
```
### 2. GPU Passthrough
```bash
# Enable GPU passthrough
export GPU_APPS="plex,jellyfin,emby"
export var_gpu="intel"
export ENABLE_PRIVILEGED="true"
```
### 3. Advanced Network Configuration
```bash
# VLAN and IPv6 configuration
export var_vlan="100"
export var_ipv6="2001:db8::100"
export IPV6_METHOD="static"
export var_mtu="9000"
```
### 4. Storage Configuration
```bash
# Custom storage locations
export var_template_storage="nfs-storage"
export var_container_storage="ssd-storage"
```
## Variable Validation
The script validates variables at several points:
1. **Container ID validation**: Must be unique and within valid range
2. **IP address validation**: Must be valid IPv4/IPv6 format
3. **Storage validation**: Must exist and support required content types
4. **Resource validation**: Must be within reasonable limits
5. **Network validation**: Must be valid network configuration
## Common Variable Combinations
### Development Container
```bash
export APP="dev-container"
export CTID="200"
export var_hostname="dev-server"
export var_os="ubuntu"
export var_version="22.04"
export var_cpu="4"
export var_ram="4096"
export var_disk="20"
export ENABLE_NESTING="true"
export ENABLE_PRIVILEGED="true"
```
### Media Server with GPU
```bash
export APP="plex"
export CTID="300"
export var_hostname="plex-server"
export var_os="debian"
export var_version="12"
export var_cpu="6"
export var_ram="8192"
export var_disk="50"
export GPU_APPS="plex"
export var_gpu="nvidia"
export ENABLE_PRIVILEGED="true"
```
### Lightweight Service
```bash
export APP="nginx"
export CTID="400"
export var_hostname="nginx-proxy"
export var_os="alpine"
export var_version="3.18"
export var_cpu="1"
export var_ram="512"
export var_disk="2"
export ENABLE_UNPRIVILEGED="true"
```

413
docs/misc/build.func/BUILD_FUNC_EXECUTION_FLOWS.md Normal file
View File

@@ -0,0 +1,413 @@
# build.func Execution Flows
## Overview
This document details the execution flows for different installation modes and scenarios in `build.func`, including variable precedence, decision trees, and workflow patterns.
## Installation Modes
### 1. Default Install Flow
**Purpose**: Uses built-in defaults with minimal user interaction
**Use Case**: Quick container creation with standard settings
```
Default Install Flow:
├── start()
│ ├── Detect execution context
│ ├── Capture hard environment variables
│ └── Set CT_TYPE="install"
├── install_script()
│ ├── Display installation mode menu
│ ├── User selects "Default Install"
│ └── Proceed with defaults
├── variables()
│ ├── base_settings() # Set built-in defaults
│ ├── Load app.vars (if exists)
│ ├── Load default.vars (if exists)
│ └── Apply variable precedence
├── build_container()
│ ├── validate_settings()
│ ├── check_conflicts()
│ └── create_lxc_container()
└── default_var_settings()
└── Offer to save as defaults
```
**Key Characteristics**:
- Minimal user prompts
- Uses built-in defaults
- Fast execution
- Suitable for standard deployments
### 2. Advanced Install Flow
**Purpose**: Full interactive configuration via whiptail menus
**Use Case**: Custom container configuration with full control
```
Advanced Install Flow:
├── start()
│ ├── Detect execution context
│ ├── Capture hard environment variables
│ └── Set CT_TYPE="install"
├── install_script()
│ ├── Display installation mode menu
│ ├── User selects "Advanced Install"
│ └── Proceed with advanced configuration
├── variables()
│ ├── base_settings() # Set built-in defaults
│ ├── Load app.vars (if exists)
│ ├── Load default.vars (if exists)
│ └── Apply variable precedence
├── advanced_settings()
│ ├── OS Selection Menu
│ ├── Resource Configuration Menu
│ ├── Network Configuration Menu
│ ├── select_storage()
│ │ ├── resolve_storage_preselect()
│ │ └── choose_and_set_storage_for_file()
│ ├── GPU Configuration Menu
│ │ └── detect_gpu_devices()
│ └── Feature Flags Menu
├── build_container()
│ ├── validate_settings()
│ ├── check_conflicts()
│ └── create_lxc_container()
└── default_var_settings()
└── Offer to save as defaults
```
**Key Characteristics**:
- Full interactive configuration
- Whiptail menus for all options
- Complete control over settings
- Suitable for custom deployments
### 3. My Defaults Flow
**Purpose**: Loads settings from global default.vars file
**Use Case**: Using previously saved global defaults
```
My Defaults Flow:
├── start()
│ ├── Detect execution context
│ ├── Capture hard environment variables
│ └── Set CT_TYPE="install"
├── install_script()
│ ├── Display installation mode menu
│ ├── User selects "My Defaults"
│ └── Proceed with loaded defaults
├── variables()
│ ├── base_settings() # Set built-in defaults
│ ├── Load app.vars (if exists)
│ ├── Load default.vars # Load global defaults
│ └── Apply variable precedence
├── build_container()
│ ├── validate_settings()
│ ├── check_conflicts()
│ └── create_lxc_container()
└── default_var_settings()
└── Offer to save as defaults
```
**Key Characteristics**:
- Uses global default.vars file
- Minimal user interaction
- Consistent with previous settings
- Suitable for repeated deployments
### 4. App Defaults Flow
**Purpose**: Loads settings from app-specific .vars file
**Use Case**: Using previously saved app-specific defaults
```
App Defaults Flow:
├── start()
│ ├── Detect execution context
│ ├── Capture hard environment variables
│ └── Set CT_TYPE="install"
├── install_script()
│ ├── Display installation mode menu
│ ├── User selects "App Defaults"
│ └── Proceed with app-specific defaults
├── variables()
│ ├── base_settings() # Set built-in defaults
│ ├── Load app.vars # Load app-specific defaults
│ ├── Load default.vars (if exists)
│ └── Apply variable precedence
├── build_container()
│ ├── validate_settings()
│ ├── check_conflicts()
│ └── create_lxc_container()
└── default_var_settings()
└── Offer to save as defaults
```
**Key Characteristics**:
- Uses app-specific .vars file
- Minimal user interaction
- App-optimized settings
- Suitable for app-specific deployments
## Variable Precedence Chain
### Precedence Order (Highest to Lowest)
1. **Hard Environment Variables**: Set before script execution
2. **App-specific .vars file**: `/usr/local/community-scripts/defaults/<app>.vars`
3. **Global default.vars file**: `/usr/local/community-scripts/default.vars`
4. **Built-in defaults**: Set in `base_settings()` function
### Variable Resolution Process
```
Variable Resolution:
├── Capture hard environment variables at start()
├── Load built-in defaults in base_settings()
├── Load global default.vars (if exists)
├── Load app-specific .vars (if exists)
└── Apply precedence chain
├── Hard env vars override all
├── App.vars override default.vars and built-ins
├── Default.vars override built-ins
└── Built-ins are fallback defaults
```
## Storage Selection Logic
### Storage Resolution Flow
```
Storage Selection:
├── Check if storage is preselected
│ ├── var_template_storage set? → Validate and use
│ └── var_container_storage set? → Validate and use
├── Count available storage options
│ ├── Only 1 option → Auto-select
│ └── Multiple options → Prompt user
├── User selection via whiptail
│ ├── Template storage selection
│ └── Container storage selection
└── Validate selected storage
├── Check availability
├── Check content type support
└── Proceed with selection
```
### Storage Validation
```
Storage Validation:
├── Check storage exists
├── Check storage is online
├── Check content type support
│ ├── Template storage: vztmpl support
│ └── Container storage: rootdir support
├── Check available space
└── Validate permissions
```
## GPU Passthrough Flow
### GPU Detection and Configuration
```
GPU Passthrough Flow:
├── detect_gpu_devices()
│ ├── Scan for Intel GPUs
│ │ ├── Check i915 driver
│ │ └── Detect devices
│ ├── Scan for AMD GPUs
│ │ ├── Check AMDGPU driver
│ │ └── Detect devices
│ └── Scan for NVIDIA GPUs
│ ├── Check NVIDIA driver
│ ├── Detect devices
│ └── Check CUDA support
├── Check GPU passthrough eligibility
│ ├── Is app in GPU_APPS list?
│ ├── Is container privileged?
│ └── Proceed if eligible
├── GPU selection logic
│ ├── Single GPU type → Auto-select
│ └── Multiple GPU types → Prompt user
├── configure_gpu_passthrough()
│ ├── Add GPU device entries
│ ├── Configure permissions
│ └── Update container config
└── fix_gpu_gids()
├── Update GPU group IDs
└── Configure access permissions
```
### GPU Eligibility Check
```
GPU Eligibility:
├── Check app support
│ ├── Is APP in GPU_APPS list?
│ └── Proceed if supported
├── Check container privileges
│ ├── Is ENABLE_PRIVILEGED="true"?
│ └── Proceed if privileged
└── Check hardware availability
├── Are GPUs detected?
└── Proceed if available
```
## Network Configuration Flow
### Network Setup Process
```
Network Configuration:
├── Basic network settings
│ ├── var_net (network interface)
│ ├── var_bridge (bridge interface)
│ └── var_gateway (gateway IP)
├── IP configuration
│ ├── var_ip (IPv4 address)
│ ├── var_ipv6 (IPv6 address)
│ └── IPV6_METHOD (IPv6 method)
├── Advanced network settings
│ ├── var_vlan (VLAN ID)
│ ├── var_mtu (MTU size)
│ └── var_mac (MAC address)
└── Network validation
├── Check IP format
├── Check gateway reachability
└── Validate network configuration
```
## Container Creation Flow
### LXC Container Creation Process
```
Container Creation:
├── create_lxc_container()
│ ├── Create basic container
│ ├── Configure network
│ ├── Set up storage
│ ├── Configure features
│ ├── Set resource limits
│ ├── Configure startup
│ └── Start container
├── Post-creation configuration
│ ├── Wait for network
│ ├── Configure GPU (if enabled)
│ ├── Set up SSH keys
│ └── Run post-install scripts
└── Finalization
├── Display container info
├── Show access details
└── Provide next steps
```
## Error Handling Flows
### Validation Error Flow
```
Validation Error Flow:
├── validate_settings()
│ ├── Check configuration validity
│ └── Return error if invalid
├── check_conflicts()
│ ├── Check for conflicts
│ └── Return error if conflicts found
├── Error handling
│ ├── Display error message
│ ├── cleanup_on_error()
│ └── Exit with error code
└── User notification
├── Show error details
└── Suggest fixes
```
### Storage Error Flow
```
Storage Error Flow:
├── Storage selection fails
├── Retry storage selection
│ ├── Show available options
│ └── Allow user to retry
├── Storage validation fails
│ ├── Show validation errors
│ └── Allow user to fix
└── Fallback to default storage
├── Use fallback storage
└── Continue with creation
```
### GPU Error Flow
```
GPU Error Flow:
├── GPU detection fails
├── Fall back to no GPU
│ ├── Disable GPU passthrough
│ └── Continue without GPU
├── GPU configuration fails
│ ├── Show configuration errors
│ └── Allow user to retry
└── GPU permission errors
├── Fix GPU permissions
└── Retry configuration
```
## Integration Flows
### With Install Scripts
```
Install Script Integration:
├── build.func creates container
├── Container starts successfully
├── Install script execution
│ ├── Download and install app
│ ├── Configure app settings
│ └── Set up services
└── Post-installation configuration
├── Verify installation
├── Configure access
└── Display completion info
```
### With Proxmox API
```
Proxmox API Integration:
├── API authentication
├── Container creation via API
├── Configuration updates via API
├── Status monitoring via API
└── Error handling via API
```
## Performance Considerations
### Execution Time Optimization
```
Performance Optimization:
├── Parallel operations where possible
├── Minimal user interaction in default mode
├── Efficient storage selection
├── Optimized GPU detection
└── Streamlined validation
```
### Resource Usage
```
Resource Usage:
├── Minimal memory footprint
├── Efficient disk usage
├── Optimized network usage
└── Minimal CPU overhead
```

244
docs/misc/build.func/BUILD_FUNC_FLOWCHART.md Normal file
View File

@@ -0,0 +1,244 @@
# build.func Execution Flowchart
## Main Execution Flow
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ START() │
│ Entry point when build.func is sourced or executed │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Check Environment │
│ • Detect if running on Proxmox host vs inside container │
│ • Capture hard environment variables │
│ • Set CT_TYPE based on context │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Determine Action │
│ • If CT_TYPE="update" → update_script() │
│ • If CT_TYPE="install" → install_script() │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ INSTALL_SCRIPT() │
│ Main container creation workflow │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Installation Mode Selection │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
│ │ Default │ │ Advanced │ │ My Defaults │ │ App Defaults│ │
│ │ Install │ │ Install │ │ │ │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ • Use built-in │ │ • Full whiptail │ │ • Load from │ │ • Load from │ │
│ │ defaults │ │ menus │ │ default.vars │ │ app.vars │ │
│ │ • Minimal │ │ • Interactive │ │ • Override │ │ • App- │ │
│ │ prompts │ │ configuration │ │ built-ins │ │ specific │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────┘ │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ VARIABLES() │
│ • Load variable precedence chain: │
│ 1. Hard environment variables │
│ 2. App-specific .vars file │
│ 3. Global default.vars file │
│ 4. Built-in defaults in base_settings() │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ BASE_SETTINGS() │
│ • Set core container parameters │
│ • Configure OS selection │
│ • Set resource defaults (CPU, RAM, Disk) │
│ • Configure network defaults │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Storage Selection Logic │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ SELECT_STORAGE() │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────┐ │ │
│ │ │ Template │ │ Container │ │ Resolution │ │ │
│ │ │ Storage │ │ Storage │ │ Logic │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ • Check if │ │ • Check if │ │ 1. Only 1 storage │ │ │
│ │ │ preselected │ │ preselected │ │ → Auto-select │ │ │
│ │ │ • Validate │ │ • Validate │ │ 2. Preselected │ │ │
│ │ │ availability │ │ availability │ │ → Validate & use │ │ │
│ │ │ • Prompt if │ │ • Prompt if │ │ 3. Multiple options │ │ │
│ │ │ needed │ │ needed │ │ → Prompt user │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ BUILD_CONTAINER() │
│ • Validate all settings │
│ • Check for conflicts │
│ • Prepare container configuration │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ CREATE_LXC_CONTAINER() │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ Container Creation Process │ │
│ │ │ │
│ │ 1. Create LXC container with basic configuration │ │
│ │ 2. Configure network settings │ │
│ │ 3. Set up storage and mount points │ │
│ │ 4. Configure features (FUSE, TUN, etc.) │ │
│ │ 5. Set resource limits │ │
│ │ 6. Configure startup options │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ GPU Passthrough Decision Tree │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ DETECT_GPU_DEVICES() │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────┐ │ │
│ │ │ Intel GPU │ │ AMD GPU │ │ NVIDIA GPU │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ • Check i915 │ │ • Check AMDGPU │ │ • Check NVIDIA │ │ │
│ │ │ driver │ │ driver │ │ driver │ │ │
│ │ │ • Detect │ │ • Detect │ │ • Detect devices │ │ │
│ │ │ devices │ │ devices │ │ • Check CUDA support │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ GPU Selection Logic │ │
│ │ │ │
│ │ • Is app in GPU_APPS list? OR Is container privileged? │ │
│ │ └─ YES → Proceed with GPU configuration │ │
│ │ └─ NO → Skip GPU passthrough │ │
│ │ │ │
│ │ • Single GPU type detected? │ │
│ │ └─ YES → Auto-select and configure │ │
│ │ └─ NO → Prompt user for selection │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ CONFIGURE_GPU_PASSTHROUGH() │
│ • Add GPU device entries to /etc/pve/lxc/<ctid>.conf │
│ • Configure proper device permissions │
│ • Set up device mapping │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Container Finalization │
│ • Start container │
│ • Wait for network connectivity │
│ • Fix GPU GIDs (if GPU passthrough enabled) │
│ • Configure SSH keys (if enabled) │
│ • Run post-installation scripts │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Settings Persistence │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ DEFAULT_VAR_SETTINGS() │ │
│ │ │ │
│ │ • Offer to save current settings as defaults │ │
│ │ • Save to /usr/local/community-scripts/default.vars │ │
│ │ • Save to /usr/local/community-scripts/defaults/<app>.vars │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ COMPLETION │
│ • Display container information │
│ • Show access details │
│ • Provide next steps │
└─────────────────────────────────────────────────────────────────────────────────┘
```
## Key Decision Points
### 1. Installation Mode Selection
- **Default**: Uses built-in defaults, minimal user interaction
- **Advanced**: Full interactive configuration via whiptail menus
- **My Defaults**: Loads settings from global default.vars file
- **App Defaults**: Loads settings from app-specific .vars file
### 2. Storage Selection Logic
```
Storage Selection Flow:
├── Check if storage is preselected via environment variables
│ ├── YES → Validate availability and use
│ └── NO → Continue to resolution logic
├── Count available storage options for content type
│ ├── Only 1 option → Auto-select
│ └── Multiple options → Prompt user via whiptail
└── Validate selected storage and proceed
```
### 3. GPU Passthrough Decision Tree
```
GPU Passthrough Flow:
├── Detect available GPU hardware
│ ├── Intel GPU detected
│ ├── AMD GPU detected
│ └── NVIDIA GPU detected
├── Check if GPU passthrough should be enabled
│ ├── App is in GPU_APPS list? → YES
│ ├── Container is privileged? → YES
│ └── Neither? → Skip GPU passthrough
├── Configure GPU passthrough
│ ├── Single GPU type → Auto-configure
│ └── Multiple GPU types → Prompt user
└── Fix GPU GIDs post-creation
```
### 4. Variable Precedence Chain
```
Variable Resolution Order:
1. Hard environment variables (captured at start)
2. App-specific .vars file (/usr/local/community-scripts/defaults/<app>.vars)
3. Global default.vars file (/usr/local/community-scripts/default.vars)
4. Built-in defaults in base_settings() function
```
## Error Handling Flow
```
Error Handling:
├── Validation errors → Display error message and exit
├── Storage errors → Retry storage selection
├── Network errors → Retry network configuration
├── GPU errors → Fall back to no GPU passthrough
└── Container creation errors → Cleanup and exit
```
## Integration Points
- **Core Functions**: Depends on core.func for basic utilities
- **Error Handling**: Uses error_handler.func for error management
- **API Functions**: Uses api.func for Proxmox API interactions
- **Tools**: Uses tools.func for additional utilities
- **Install Scripts**: Integrates with <app>-install.sh scripts

361
docs/misc/build.func/BUILD_FUNC_FUNCTIONS_REFERENCE.md Normal file
View File

@@ -0,0 +1,361 @@
# build.func Functions Reference
## Overview
This document provides a comprehensive reference of all functions in `build.func`, organized alphabetically with detailed descriptions, parameters, and usage information.
## Function Categories
### Initialization Functions
#### `start()`
**Purpose**: Main entry point when build.func is sourced or executed
**Parameters**: None
**Returns**: None
**Side Effects**:
- Detects execution context (Proxmox host vs container)
- Captures hard environment variables
- Sets CT_TYPE based on context
- Routes to appropriate workflow (install_script or update_script)
**Dependencies**: None
**Environment Variables Used**: `CT_TYPE`, `APP`, `CTID`
#### `variables()`
**Purpose**: Load and resolve all configuration variables using precedence chain
**Parameters**: None
**Returns**: None
**Side Effects**:
- Loads app-specific .vars file
- Loads global default.vars file
- Applies variable precedence chain
- Sets all configuration variables
**Dependencies**: `base_settings()`
**Environment Variables Used**: All configuration variables
#### `base_settings()`
**Purpose**: Set built-in default values for all configuration variables
**Parameters**: None
**Returns**: None
**Side Effects**: Sets default values for all variables
**Dependencies**: None
**Environment Variables Used**: All configuration variables
### UI and Menu Functions
#### `install_script()`
**Purpose**: Main installation workflow coordinator
**Parameters**: None
**Returns**: None
**Side Effects**:
- Displays installation mode selection menu
- Coordinates the entire installation process
- Handles user interaction and validation
**Dependencies**: `variables()`, `build_container()`, `default_var_settings()`
**Environment Variables Used**: `APP`, `CTID`, `var_hostname`
#### `advanced_settings()`
**Purpose**: Provide advanced configuration options via whiptail menus
**Parameters**: None
**Returns**: None
**Side Effects**:
- Displays whiptail menus for configuration
- Updates configuration variables based on user input
- Validates user selections
**Dependencies**: `select_storage()`, `detect_gpu_devices()`
**Environment Variables Used**: All configuration variables
#### `settings_menu()`
**Purpose**: Display and handle settings configuration menu
**Parameters**: None
**Returns**: None
**Side Effects**: Updates configuration variables
**Dependencies**: `advanced_settings()`
**Environment Variables Used**: All configuration variables
### Storage Functions
#### `select_storage()`
**Purpose**: Handle storage selection for templates and containers
**Parameters**: None
**Returns**: None
**Side Effects**:
- Resolves storage preselection
- Prompts user for storage selection if needed
- Validates storage availability
- Sets var_template_storage and var_container_storage
**Dependencies**: `resolve_storage_preselect()`, `choose_and_set_storage_for_file()`
**Environment Variables Used**: `var_template_storage`, `var_container_storage`, `TEMPLATE_STORAGE`, `CONTAINER_STORAGE`
#### `resolve_storage_preselect()`
**Purpose**: Resolve preselected storage options
**Parameters**:
- `storage_type`: Type of storage (template or container)
**Returns**: Storage name if valid, empty if invalid
**Side Effects**: Validates storage availability
**Dependencies**: None
**Environment Variables Used**: `var_template_storage`, `var_container_storage`
#### `choose_and_set_storage_for_file()`
**Purpose**: Interactive storage selection via whiptail
**Parameters**:
- `storage_type`: Type of storage (template or container)
- `content_type`: Content type (vztmpl or rootdir)
**Returns**: None
**Side Effects**:
- Displays whiptail menu
- Updates storage variables
- Validates selection
**Dependencies**: None
**Environment Variables Used**: `var_template_storage`, `var_container_storage`
### Container Creation Functions
#### `build_container()`
**Purpose**: Validate settings and prepare container creation
**Parameters**: None
**Returns**: None
**Side Effects**:
- Validates all configuration
- Checks for conflicts
- Prepares container configuration
- Calls create_lxc_container()
**Dependencies**: `create_lxc_container()`
**Environment Variables Used**: All configuration variables
#### `create_lxc_container()`
**Purpose**: Create the actual LXC container
**Parameters**: None
**Returns**: None
**Side Effects**:
- Creates LXC container with basic configuration
- Configures network settings
- Sets up storage and mount points
- Configures features (FUSE, TUN, etc.)
- Sets resource limits
- Configures startup options
- Starts container
**Dependencies**: `configure_gpu_passthrough()`, `fix_gpu_gids()`
**Environment Variables Used**: All configuration variables
### GPU and Hardware Functions
#### `detect_gpu_devices()`
**Purpose**: Detect available GPU hardware on the system
**Parameters**: None
**Returns**: None
**Side Effects**:
- Scans for Intel, AMD, and NVIDIA GPUs
- Updates var_gpu_type and var_gpu_devices
- Determines GPU capabilities
**Dependencies**: None
**Environment Variables Used**: `var_gpu_type`, `var_gpu_devices`, `GPU_APPS`
#### `configure_gpu_passthrough()`
**Purpose**: Configure GPU passthrough for the container
**Parameters**: None
**Returns**: None
**Side Effects**:
- Adds GPU device entries to container config
- Configures proper device permissions
- Sets up device mapping
- Updates /etc/pve/lxc/<ctid>.conf
**Dependencies**: `detect_gpu_devices()`
**Environment Variables Used**: `var_gpu`, `var_gpu_type`, `var_gpu_devices`, `CTID`
#### `fix_gpu_gids()`
**Purpose**: Fix GPU group IDs after container creation
**Parameters**: None
**Returns**: None
**Side Effects**:
- Updates GPU group IDs in container
- Ensures proper GPU access permissions
- Configures video and render groups
**Dependencies**: `configure_gpu_passthrough()`
**Environment Variables Used**: `CTID`, `var_gpu_type`
### Settings Persistence Functions
#### `default_var_settings()`
**Purpose**: Offer to save current settings as defaults
**Parameters**: None
**Returns**: None
**Side Effects**:
- Prompts user to save settings
- Saves to default.vars file
- Saves to app-specific .vars file
**Dependencies**: `maybe_offer_save_app_defaults()`
**Environment Variables Used**: All configuration variables
#### `maybe_offer_save_app_defaults()`
**Purpose**: Offer to save app-specific defaults
**Parameters**: None
**Returns**: None
**Side Effects**:
- Prompts user to save app-specific settings
- Saves to app.vars file
- Updates app-specific configuration
**Dependencies**: None
**Environment Variables Used**: `APP`, `SAVE_APP_DEFAULTS`
### Utility Functions
#### `validate_settings()`
**Purpose**: Validate all configuration settings
**Parameters**: None
**Returns**: 0 if valid, 1 if invalid
**Side Effects**:
- Checks for configuration conflicts
- Validates resource limits
- Validates network configuration
- Validates storage configuration
**Dependencies**: None
**Environment Variables Used**: All configuration variables
#### `check_conflicts()`
**Purpose**: Check for configuration conflicts
**Parameters**: None
**Returns**: 0 if no conflicts, 1 if conflicts found
**Side Effects**:
- Checks for conflicting settings
- Validates resource allocation
- Checks network configuration
**Dependencies**: None
**Environment Variables Used**: All configuration variables
#### `cleanup_on_error()`
**Purpose**: Clean up resources on error
**Parameters**: None
**Returns**: None
**Side Effects**:
- Removes partially created containers
- Cleans up temporary files
- Resets configuration
**Dependencies**: None
**Environment Variables Used**: `CTID`
## Function Call Flow
### Main Installation Flow
```
start()
├── variables()
│ ├── base_settings()
│ ├── Load app.vars
│ └── Load default.vars
├── install_script()
│ ├── advanced_settings()
│ │ ├── select_storage()
│ │ │ ├── resolve_storage_preselect()
│ │ │ └── choose_and_set_storage_for_file()
│ │ └── detect_gpu_devices()
│ ├── build_container()
│ │ ├── validate_settings()
│ │ ├── check_conflicts()
│ │ └── create_lxc_container()
│ │ ├── configure_gpu_passthrough()
│ │ └── fix_gpu_gids()
│ └── default_var_settings()
│ └── maybe_offer_save_app_defaults()
```
### Error Handling Flow
```
Error Detection
├── validate_settings()
│ └── check_conflicts()
├── Error Handling
│ └── cleanup_on_error()
└── Exit with error code
```
## Function Dependencies
### Core Dependencies
- `start()` → `install_script()` → `build_container()` → `create_lxc_container()`
- `variables()` → `base_settings()`
- `advanced_settings()` → `select_storage()` → `detect_gpu_devices()`
### Storage Dependencies
- `select_storage()` → `resolve_storage_preselect()`
- `select_storage()` → `choose_and_set_storage_for_file()`
### GPU Dependencies
- `configure_gpu_passthrough()` → `detect_gpu_devices()`
- `fix_gpu_gids()` → `configure_gpu_passthrough()`
### Settings Dependencies
- `default_var_settings()` → `maybe_offer_save_app_defaults()`
## Function Usage Examples
### Basic Container Creation
```bash
# Set required variables
export APP="plex"
export CTID="100"
export var_hostname="plex-server"
# Call main functions
start() # Entry point
# → variables() # Load configuration
# → install_script() # Main workflow
# → build_container() # Create container
# → create_lxc_container() # Actual creation
```
### Advanced Configuration
```bash
# Set advanced variables
export var_os="debian"
export var_version="12"
export var_cpu="4"
export var_ram="4096"
export var_disk="20"
# Call advanced functions
advanced_settings() # Interactive configuration
# → select_storage() # Storage selection
# → detect_gpu_devices() # GPU detection
```
### GPU Passthrough
```bash
# Enable GPU passthrough
export GPU_APPS="plex"
export var_gpu="nvidia"
# Call GPU functions
detect_gpu_devices() # Detect hardware
configure_gpu_passthrough() # Configure passthrough
fix_gpu_gids() # Fix permissions
```
### Settings Persistence
```bash
# Save settings as defaults
export SAVE_DEFAULTS="true"
export SAVE_APP_DEFAULTS="true"
# Call persistence functions
default_var_settings() # Save global defaults
maybe_offer_save_app_defaults() # Save app defaults
```
## Function Error Handling
### Validation Functions
- `validate_settings()`: Returns 0 for valid, 1 for invalid
- `check_conflicts()`: Returns 0 for no conflicts, 1 for conflicts
### Error Recovery
- `cleanup_on_error()`: Cleans up on any error
- Error codes are propagated up the call stack
- Critical errors cause script termination
### Error Types
1. **Configuration Errors**: Invalid settings or conflicts
2. **Resource Errors**: Insufficient resources or conflicts
3. **Network Errors**: Invalid network configuration
4. **Storage Errors**: Storage not available or invalid
5. **GPU Errors**: GPU configuration failures
6. **Container Creation Errors**: LXC creation failures

600
docs/misc/build.func/BUILD_FUNC_USAGE_EXAMPLES.md Normal file
View File

@@ -0,0 +1,600 @@
# build.func Usage Examples
## Overview
This document provides practical usage examples for `build.func`, covering common scenarios, CLI examples, and environment variable combinations.
## Basic Usage Examples
### 1. Simple Container Creation
**Scenario**: Create a basic Plex media server container
```bash
# Set basic environment variables
export APP="plex"
export CTID="100"
export var_hostname="plex-server"
export var_os="debian"
export var_version="12"
export var_cpu="4"
export var_ram="4096"
export var_disk="20"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.100"
export var_template_storage="local"
export var_container_storage="local"
# Execute build.func
source build.func
```
**Expected Output**:
```
Creating Plex container...
Container ID: 100
Hostname: plex-server
OS: Debian 12
Resources: 4 CPU, 4GB RAM, 20GB Disk
Network: 192.168.1.100/24
Container created successfully!
```
### 2. Advanced Configuration
**Scenario**: Create a Nextcloud container with custom settings
```bash
# Set advanced environment variables
export APP="nextcloud"
export CTID="101"
export var_hostname="nextcloud-server"
export var_os="ubuntu"
export var_version="22.04"
export var_cpu="6"
export var_ram="8192"
export var_disk="50"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.101"
export var_vlan="100"
export var_mtu="9000"
export var_template_storage="nfs-storage"
export var_container_storage="ssd-storage"
export ENABLE_FUSE="true"
export ENABLE_TUN="true"
export SSH="true"
# Execute build.func
source build.func
```
### 3. GPU Passthrough Configuration
**Scenario**: Create a Jellyfin container with NVIDIA GPU passthrough
```bash
# Set GPU passthrough variables
export APP="jellyfin"
export CTID="102"
export var_hostname="jellyfin-server"
export var_os="debian"
export var_version="12"
export var_cpu="8"
export var_ram="16384"
export var_disk="30"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.102"
export var_template_storage="local"
export var_container_storage="local"
export GPU_APPS="jellyfin"
export var_gpu="nvidia"
export ENABLE_PRIVILEGED="true"
export ENABLE_FUSE="true"
export ENABLE_TUN="true"
# Execute build.func
source build.func
```
## Silent/Non-Interactive Examples
### 1. Automated Deployment
**Scenario**: Deploy multiple containers without user interaction
```bash
#!/bin/bash
# Automated deployment script
# Function to create container
create_container() {
local app=$1
local ctid=$2
local ip=$3
export APP="$app"
export CTID="$ctid"
export var_hostname="${app}-server"
export var_os="debian"
export var_version="12"
export var_cpu="2"
export var_ram="2048"
export var_disk="10"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="$ip"
export var_template_storage="local"
export var_container_storage="local"
export ENABLE_FUSE="true"
export ENABLE_TUN="true"
export SSH="true"
source build.func
}
# Create multiple containers
create_container "plex" "100" "192.168.1.100"
create_container "nextcloud" "101" "192.168.1.101"
create_container "nginx" "102" "192.168.1.102"
```
### 2. Development Environment Setup
**Scenario**: Create development containers with specific configurations
```bash
#!/bin/bash
# Development environment setup
# Development container configuration
export APP="dev-container"
export CTID="200"
export var_hostname="dev-server"
export var_os="ubuntu"
export var_version="22.04"
export var_cpu="4"
export var_ram="4096"
export var_disk="20"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.200"
export var_template_storage="local"
export var_container_storage="local"
export ENABLE_NESTING="true"
export ENABLE_PRIVILEGED="true"
export ENABLE_FUSE="true"
export ENABLE_TUN="true"
export SSH="true"
# Execute build.func
source build.func
```
## Network Configuration Examples
### 1. VLAN Configuration
**Scenario**: Create container with VLAN support
```bash
# VLAN configuration
export APP="web-server"
export CTID="300"
export var_hostname="web-server"
export var_os="debian"
export var_version="12"
export var_cpu="2"
export var_ram="2048"
export var_disk="10"
export var_net="vmbr0"
export var_gateway="192.168.100.1"
export var_ip="192.168.100.100"
export var_vlan="100"
export var_mtu="1500"
export var_template_storage="local"
export var_container_storage="local"
source build.func
```
### 2. IPv6 Configuration
**Scenario**: Create container with IPv6 support
```bash
# IPv6 configuration
export APP="ipv6-server"
export CTID="301"
export var_hostname="ipv6-server"
export var_os="debian"
export var_version="12"
export var_cpu="2"
export var_ram="2048"
export var_disk="10"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.101"
export var_ipv6="2001:db8::101"
export IPV6_METHOD="static"
export var_template_storage="local"
export var_container_storage="local"
source build.func
```
## Storage Configuration Examples
### 1. Custom Storage Locations
**Scenario**: Use different storage for templates and containers
```bash
# Custom storage configuration
export APP="storage-test"
export CTID="400"
export var_hostname="storage-test"
export var_os="debian"
export var_version="12"
export var_cpu="2"
export var_ram="2048"
export var_disk="10"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.140"
export var_template_storage="nfs-storage"
export var_container_storage="ssd-storage"
source build.func
```
### 2. High-Performance Storage
**Scenario**: Use high-performance storage for resource-intensive applications
```bash
# High-performance storage configuration
export APP="database-server"
export CTID="401"
export var_hostname="database-server"
export var_os="debian"
export var_version="12"
export var_cpu="8"
export var_ram="16384"
export var_disk="100"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.141"
export var_template_storage="nvme-storage"
export var_container_storage="nvme-storage"
source build.func
```
## Feature Configuration Examples
### 1. Privileged Container
**Scenario**: Create privileged container for system-level access
```bash
# Privileged container configuration
export APP="system-container"
export CTID="500"
export var_hostname="system-container"
export var_os="debian"
export var_version="12"
export var_cpu="4"
export var_ram="4096"
export var_disk="20"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.150"
export var_template_storage="local"
export var_container_storage="local"
export ENABLE_PRIVILEGED="true"
export ENABLE_FUSE="true"
export ENABLE_TUN="true"
export ENABLE_KEYCTL="true"
export ENABLE_MOUNT="true"
source build.func
```
### 2. Unprivileged Container
**Scenario**: Create secure unprivileged container
```bash
# Unprivileged container configuration
export APP="secure-container"
export CTID="501"
export var_hostname="secure-container"
export var_os="debian"
export var_version="12"
export var_cpu="2"
export var_ram="2048"
export var_disk="10"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.151"
export var_template_storage="local"
export var_container_storage="local"
export ENABLE_UNPRIVILEGED="true"
export ENABLE_FUSE="true"
export ENABLE_TUN="true"
source build.func
```
## Settings Persistence Examples
### 1. Save Global Defaults
**Scenario**: Save current settings as global defaults
```bash
# Save global defaults
export APP="default-test"
export CTID="600"
export var_hostname="default-test"
export var_os="debian"
export var_version="12"
export var_cpu="2"
export var_ram="2048"
export var_disk="10"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.160"
export var_template_storage="local"
export var_container_storage="local"
export SAVE_DEFAULTS="true"
source build.func
```
### 2. Save App-Specific Defaults
**Scenario**: Save settings as app-specific defaults
```bash
# Save app-specific defaults
export APP="plex"
export CTID="601"
export var_hostname="plex-server"
export var_os="debian"
export var_version="12"
export var_cpu="4"
export var_ram="4096"
export var_disk="20"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.161"
export var_template_storage="local"
export var_container_storage="local"
export SAVE_APP_DEFAULTS="true"
source build.func
```
## Error Handling Examples
### 1. Validation Error Handling
**Scenario**: Handle configuration validation errors
```bash
#!/bin/bash
# Error handling example
# Set invalid configuration
export APP="error-test"
export CTID="700"
export var_hostname="error-test"
export var_os="invalid-os"
export var_version="invalid-version"
export var_cpu="invalid-cpu"
export var_ram="invalid-ram"
export var_disk="invalid-disk"
export var_net="invalid-network"
export var_gateway="invalid-gateway"
export var_ip="invalid-ip"
# Execute with error handling
if source build.func; then
echo "Container created successfully!"
else
echo "Error: Container creation failed!"
echo "Please check your configuration and try again."
fi
```
### 2. Storage Error Handling
**Scenario**: Handle storage selection errors
```bash
#!/bin/bash
# Storage error handling
# Set invalid storage
export APP="storage-error-test"
export CTID="701"
export var_hostname="storage-error-test"
export var_os="debian"
export var_version="12"
export var_cpu="2"
export var_ram="2048"
export var_disk="10"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.170"
export var_template_storage="nonexistent-storage"
export var_container_storage="nonexistent-storage"
# Execute with error handling
if source build.func; then
echo "Container created successfully!"
else
echo "Error: Storage not available!"
echo "Please check available storage and try again."
fi
```
## Integration Examples
### 1. With Install Scripts
**Scenario**: Integrate with application install scripts
```bash
#!/bin/bash
# Integration with install scripts
# Create container
export APP="plex"
export CTID="800"
export var_hostname="plex-server"
export var_os="debian"
export var_version="12"
export var_cpu="4"
export var_ram="4096"
export var_disk="20"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.180"
export var_template_storage="local"
export var_container_storage="local"
# Create container
source build.func
# Run install script
if [ -f "plex-install.sh" ]; then
source plex-install.sh
else
echo "Install script not found!"
fi
```
### 2. With Monitoring
**Scenario**: Integrate with monitoring systems
```bash
#!/bin/bash
# Monitoring integration
# Create container with monitoring
export APP="monitored-app"
export CTID="801"
export var_hostname="monitored-app"
export var_os="debian"
export var_version="12"
export var_cpu="2"
export var_ram="2048"
export var_disk="10"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.181"
export var_template_storage="local"
export var_container_storage="local"
export DIAGNOSTICS="true"
# Create container
source build.func
# Set up monitoring
if [ -f "monitoring-setup.sh" ]; then
source monitoring-setup.sh
fi
```
## Best Practices
### 1. Environment Variable Management
```bash
#!/bin/bash
# Best practice: Environment variable management
# Set configuration file
CONFIG_FILE="/etc/build.func.conf"
# Load configuration if exists
if [ -f "$CONFIG_FILE" ]; then
source "$CONFIG_FILE"
fi
# Set required variables
export APP="${APP:-plex}"
export CTID="${CTID:-100}"
export var_hostname="${var_hostname:-plex-server}"
export var_os="${var_os:-debian}"
export var_version="${var_version:-12}"
export var_cpu="${var_cpu:-2}"
export var_ram="${var_ram:-2048}"
export var_disk="${var_disk:-10}"
export var_net="${var_net:-vmbr0}"
export var_gateway="${var_gateway:-192.168.1.1}"
export var_ip="${var_ip:-192.168.1.100}"
export var_template_storage="${var_template_storage:-local}"
export var_container_storage="${var_container_storage:-local}"
# Execute build.func
source build.func
```
### 2. Error Handling and Logging
```bash
#!/bin/bash
# Best practice: Error handling and logging
# Set log file
LOG_FILE="/var/log/build.func.log"
# Function to log messages
log_message() {
echo "$(date): $1" >> "$LOG_FILE"
}
# Function to create container with error handling
create_container() {
local app=$1
local ctid=$2
log_message "Starting container creation for $app (ID: $ctid)"
# Set variables
export APP="$app"
export CTID="$ctid"
export var_hostname="${app}-server"
export var_os="debian"
export var_version="12"
export var_cpu="2"
export var_ram="2048"
export var_disk="10"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.$ctid"
export var_template_storage="local"
export var_container_storage="local"
# Create container
if source build.func; then
log_message "Container $app created successfully (ID: $ctid)"
return 0
else
log_message "Error: Failed to create container $app (ID: $ctid)"
return 1
fi
}
# Create containers
create_container "plex" "100"
create_container "nextcloud" "101"
create_container "nginx" "102"
```

260
docs/misc/build.func/README.md Normal file
View File

@@ -0,0 +1,260 @@
# build.func Documentation
## Overview
This directory contains comprehensive documentation for the `build.func` script, which is the core orchestration script for Proxmox LXC container creation in the Community Scripts project.
## Documentation Files
### 📊 [BUILD_FUNC_FLOWCHART.md](./BUILD_FUNC_FLOWCHART.md)
Visual ASCII flowchart showing the main execution flow, decision trees, and key decision points in the build.func script.
**Contents:**
- Main execution flow diagram
- Installation mode selection flows
- Storage selection workflow
- GPU passthrough decision logic
- Variable precedence chain
- Error handling flow
- Integration points
### 🔧 [BUILD_FUNC_ENVIRONMENT_VARIABLES.md](./BUILD_FUNC_ENVIRONMENT_VARIABLES.md)
Complete reference of all environment variables used in build.func, organized by category and usage context.
**Contents:**
- Core container variables
- Operating system variables
- Resource configuration variables
- Network configuration variables
- Storage configuration variables
- Feature flags
- GPU passthrough variables
- API and diagnostics variables
- Settings persistence variables
- Variable precedence chain
- Critical variables for non-interactive use
- Common variable combinations
### 📚 [BUILD_FUNC_FUNCTIONS_REFERENCE.md](./BUILD_FUNC_FUNCTIONS_REFERENCE.md)
Alphabetical function reference with detailed descriptions, parameters, dependencies, and usage information.
**Contents:**
- Initialization functions
- UI and menu functions
- Storage functions
- Container creation functions
- GPU and hardware functions
- Settings persistence functions
- Utility functions
- Function call flow
- Function dependencies
- Function usage examples
- Function error handling
### 🔄 [BUILD_FUNC_EXECUTION_FLOWS.md](./BUILD_FUNC_EXECUTION_FLOWS.md)
Detailed execution flows for different installation modes and scenarios, including variable precedence and decision trees.
**Contents:**
- Default install flow
- Advanced install flow
- My defaults flow
- App defaults flow
- Variable precedence chain
- Storage selection logic
- GPU passthrough flow
- Network configuration flow
- Container creation flow
- Error handling flows
- Integration flows
- Performance considerations
### 🏗️ [BUILD_FUNC_ARCHITECTURE.md](./BUILD_FUNC_ARCHITECTURE.md)
High-level architectural overview including module dependencies, data flow, integration points, and system architecture.
**Contents:**
- High-level architecture diagram
- Module dependencies
- Data flow architecture
- Integration architecture
- System architecture components
- User interface components
- Security architecture
- Performance architecture
- Deployment architecture
- Maintenance architecture
- Future architecture considerations
### 💡 [BUILD_FUNC_USAGE_EXAMPLES.md](./BUILD_FUNC_USAGE_EXAMPLES.md)
Practical usage examples covering common scenarios, CLI examples, and environment variable combinations.
**Contents:**
- Basic usage examples
- Silent/non-interactive examples
- Network configuration examples
- Storage configuration examples
- Feature configuration examples
- Settings persistence examples
- Error handling examples
- Integration examples
- Best practices
## Quick Start Guide
### For New Users
1. Start with [BUILD_FUNC_FLOWCHART.md](./BUILD_FUNC_FLOWCHART.md) to understand the overall flow
2. Review [BUILD_FUNC_ENVIRONMENT_VARIABLES.md](./BUILD_FUNC_ENVIRONMENT_VARIABLES.md) for configuration options
3. Follow examples in [BUILD_FUNC_USAGE_EXAMPLES.md](./BUILD_FUNC_USAGE_EXAMPLES.md)
### For Developers
1. Read [BUILD_FUNC_ARCHITECTURE.md](./BUILD_FUNC_ARCHITECTURE.md) for system overview
2. Study [BUILD_FUNC_FUNCTIONS_REFERENCE.md](./BUILD_FUNC_FUNCTIONS_REFERENCE.md) for function details
3. Review [BUILD_FUNC_EXECUTION_FLOWS.md](./BUILD_FUNC_EXECUTION_FLOWS.md) for implementation details
### For System Administrators
1. Focus on [BUILD_FUNC_USAGE_EXAMPLES.md](./BUILD_FUNC_USAGE_EXAMPLES.md) for deployment scenarios
2. Review [BUILD_FUNC_ENVIRONMENT_VARIABLES.md](./BUILD_FUNC_ENVIRONMENT_VARIABLES.md) for configuration management
3. Check [BUILD_FUNC_ARCHITECTURE.md](./BUILD_FUNC_ARCHITECTURE.md) for security and performance considerations
## Key Concepts
### Variable Precedence
Variables are resolved in this order (highest to lowest priority):
1. Hard environment variables (set before script execution)
2. App-specific .vars file (`/usr/local/community-scripts/defaults/<app>.vars`)
3. Global default.vars file (`/usr/local/community-scripts/default.vars`)
4. Built-in defaults (set in `base_settings()` function)
### Installation Modes
- **Default Install**: Uses built-in defaults, minimal prompts
- **Advanced Install**: Full interactive configuration via whiptail
- **My Defaults**: Loads from global default.vars file
- **App Defaults**: Loads from app-specific .vars file
### Storage Selection Logic
1. If only 1 storage exists for content type → auto-select
2. If preselected via environment variables → validate and use
3. Otherwise → prompt user via whiptail
### GPU Passthrough Flow
1. Detect hardware (Intel/AMD/NVIDIA)
2. Check if app is in GPU_APPS list OR container is privileged
3. Auto-select if single GPU type, prompt if multiple
4. Configure `/etc/pve/lxc/<ctid>.conf` with proper device entries
5. Fix GIDs post-creation to match container's video/render groups
## Common Use Cases
### Basic Container Creation
```bash
export APP="plex"
export CTID="100"
export var_hostname="plex-server"
export var_os="debian"
export var_version="12"
export var_cpu="4"
export var_ram="4096"
export var_disk="20"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.100"
export var_template_storage="local"
export var_container_storage="local"
source build.func
```
### GPU Passthrough
```bash
export APP="jellyfin"
export CTID="101"
export var_hostname="jellyfin-server"
export var_os="debian"
export var_version="12"
export var_cpu="8"
export var_ram="16384"
export var_disk="30"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.101"
export var_template_storage="local"
export var_container_storage="local"
export GPU_APPS="jellyfin"
export var_gpu="nvidia"
export ENABLE_PRIVILEGED="true"
source build.func
```
### Silent/Non-Interactive Deployment
```bash
#!/bin/bash
# Automated deployment
export APP="nginx"
export CTID="102"
export var_hostname="nginx-proxy"
export var_os="alpine"
export var_version="3.18"
export var_cpu="1"
export var_ram="512"
export var_disk="2"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.102"
export var_template_storage="local"
export var_container_storage="local"
export ENABLE_UNPRIVILEGED="true"
source build.func
```
## Troubleshooting
### Common Issues
1. **Container creation fails**: Check resource availability and configuration validity
2. **Storage errors**: Verify storage exists and supports required content types
3. **Network errors**: Validate network configuration and IP address availability
4. **GPU passthrough issues**: Check hardware detection and container privileges
5. **Permission errors**: Verify user permissions and container privileges
### Debug Mode
Enable verbose output for debugging:
```bash
export VERBOSE="true"
export DIAGNOSTICS="true"
source build.func
```
### Log Files
Check system logs for detailed error information:
- `/var/log/syslog`
- `/var/log/pve/lxc/<ctid>.log`
- Container-specific logs
## Contributing
When contributing to build.func documentation:
1. Update relevant documentation files
2. Add examples for new features
3. Update architecture diagrams if needed
4. Test all examples before submitting
5. Follow the existing documentation style
## Related Documentation
- [Main README](../../README.md) - Project overview
- [Installation Guide](../../install/) - Installation scripts
- [Container Templates](../../ct/) - Container templates
- [Tools](../../tools/) - Additional tools and utilities
## Support
For issues and questions:
1. Check this documentation first
2. Review the [troubleshooting section](#troubleshooting)
3. Check existing issues in the project repository
4. Create a new issue with detailed information
---
*Last updated: $(date)*
*Documentation version: 1.0*