ProxmoxVE/docs/misc/build.func/BUILD_FUNC_USAGE_EXAMPLES.md

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

# 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

# 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="ssd-storage"
export var_container_storage="ssd-storage"
export var_fuse="yes"
export var_tun="yes"
export SSH="true"

# Execute build.func
source build.func

3. GPU Passthrough Configuration

Scenario: Create a Jellyfin container with NVIDIA GPU passthrough

# 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

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

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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

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

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

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

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

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