ProxmoxVED/docs/misc/build.func/BUILD_FUNC_EXECUTION_FLOWS.md

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