mirror of
https://github.com/community-scripts/ProxmoxVED.git
synced 2026-02-25 05:57:26 +00:00
Add docs for all files in /misc
This commit is contained in:
Michel Roegl-Brunner
413
docs/misc/build.func/BUILD_FUNC_EXECUTION_FLOWS.md
Normal file
413
docs/misc/build.func/BUILD_FUNC_EXECUTION_FLOWS.md
Normal 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
|
||||
```
|
||||
Reference in New Issue
Block a user