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

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

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

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

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

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

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

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 to understand the overall flow
2. Review BUILD_FUNC_ENVIRONMENT_VARIABLES.md for configuration options
3. Follow examples in BUILD_FUNC_USAGE_EXAMPLES.md

For Developers

1. Read BUILD_FUNC_ARCHITECTURE.md for system overview
2. Study BUILD_FUNC_FUNCTIONS_REFERENCE.md for function details
3. Review BUILD_FUNC_EXECUTION_FLOWS.md for implementation details

For System Administrators

1. Focus on BUILD_FUNC_USAGE_EXAMPLES.md for deployment scenarios
2. Review BUILD_FUNC_ENVIRONMENT_VARIABLES.md for configuration management
3. Check 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

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

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

#!/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:

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 - Project overview
• Installation Guide - Installation scripts
• Container Templates - Container templates
• Tools - Additional tools and utilities

Support

For issues and questions:

1. Check this documentation first
2. Review the troubleshooting section
3. Check existing issues in the project repository
4. Create a new issue with detailed information

---

Last updated: $(date) Documentation version: 1.0