feat: Add var_gpu flag for GPU passthrough configuration (#9764 )

* feat: Add var_gpu flag for GPU passthrough configuration

Changes:
- Add var_gpu variable to CT scripts for explicit GPU control
- Remove hardcoded GPU_APPS list - GPU detection now uses var_gpu flag
- Add var_gpu to VAR_WHITELIST for persistence in default.vars and app.vars
- Add GPU Passthrough option (Step 19) to advanced_settings wizard (now 20 steps)
- Update documentation

Apps with var_gpu=yes (GPU enabled by default):
- Media: jellyfin, plex, emby, channels, ersatztv, tunarr
- Transcoding: tdarr, unmanic, fileflows
- AI/ML: ollama, openwebui
- NVR: frigate, immich

Usage:
- Disable GPU: var_gpu=no bash -c '$(curl -fsSL ...jellyfin.sh)'
- Enable GPU: var_gpu=yes bash -c '$(curl -fsSL ...debian.sh)'
- Via default.vars: echo 'var_gpu=yes' >> /usr/local/community-scripts/default.vars
- Via advanced settings wizard (Step 19)

* fix: tput rmcup timing, GPU line indentation, echo_default GPU display

* style: add GPU icon variable for consistent formatting

2025-12-08 13:52:30 +01:00

12 KiB

Raw Blame History

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
`var_gpu`	Enable GPU passthrough	"no"	CT script / Environment / Advanced Settings	GPU passthrough
`ENABLE_GPU`	GPU passthrough flag (internal)	"no"	Advanced Settings	Container creation

Note: GPU passthrough is controlled via var_gpu. Apps that benefit from GPU acceleration (media servers, AI/ML, transcoding) have var_gpu=yes as default in their CT scripts.

Apps with GPU enabled by default:

Media: jellyfin, plex, emby, channels, ersatztv, tunarr, immich
Transcoding: tdarr, unmanic, fileflows
AI/ML: ollama, openwebui
NVR: frigate

Usage Examples:

# Disable GPU for a specific installation
var_gpu=no bash -c "$(curl -fsSL https://...jellyfin.sh)"

# Enable GPU for apps without default GPU support
var_gpu=yes bash -c "$(curl -fsSL https://...debian.sh)"

# Set in default.vars for all apps
echo "var_gpu=yes" >> /usr/local/community-scripts/default.vars

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):

Hard Environment Variables: Set before script execution
App-specific .vars file: /usr/local/community-scripts/defaults/<app>.vars
Global default.vars file: /usr/local/community-scripts/default.vars
Built-in defaults: Set in base_settings() function

Critical Variables for Non-Interactive Use

For silent/non-interactive execution, these variables must be set:

# 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

# 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

# Enable GPU passthrough
export GPU_APPS="plex,jellyfin,emby"
export var_gpu="intel"
export ENABLE_PRIVILEGED="true"

3. Advanced Network Configuration

# 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

# Custom storage locations
export var_template_storage="nfs-storage"
export var_container_storage="ssd-storage"

Variable Validation

The script validates variables at several points:

Container ID validation: Must be unique and within valid range
IP address validation: Must be valid IPv4/IPv6 format
Storage validation: Must exist and support required content types
Resource validation: Must be within reasonable limits
Network validation: Must be valid network configuration

Common Variable Combinations

Development Container

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

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

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"

12 KiB Raw Blame History