Skip to content

Feature/advanced settings inherit app defaults #9776

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
MickLesk wants to merge 3 commits into
base: main
Choose a base branch
from
+512 −60
Draft

Feature/advanced settings inherit app defaults #9776

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8b94082
feat: inherit app defaults in advanced settings wizard
MickLesk Dec 8, 2025
6bf6da0
feat: complete advanced settings with all var_* options
MickLesk Dec 8, 2025
b83ac2b
fix: pre-fill timezone with host timezone in advanced settings
MickLesk Dec 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
164 changes: 164 additions & 0 deletions docs/misc/build.func/BUILD_FUNC_ADVANCED_SETTINGS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,164 @@
# Advanced Settings Wizard Reference

## Overview

The Advanced Settings wizard provides a 28-step interactive configuration for LXC container creation. It allows users to customize every aspect of the container while inheriting sensible defaults from the CT script.

## Key Features

- **Inherit App Defaults**: All `var_*` values from CT scripts pre-populate wizard fields
- **Back Navigation**: Press Cancel/Back to return to previous step
- **App Default Hints**: Each dialog shows `(App default: X)` to indicate script defaults
- **Full Customization**: Every configurable option is accessible

## Wizard Steps

| Step | Title | Variable(s) | Description |
| ---- | ------------------------ | --------------------------------- | ----------------------------------------------------- |
| 1 | Container Type | `var_unprivileged` | Privileged (0) or Unprivileged (1) container |
| 2 | Root Password | `var_pw` | Set password or use automatic login |
| 3 | Container ID | `var_ctid` | Unique container ID (auto-suggested) |
| 4 | Hostname | `var_hostname` | Container hostname |
| 5 | Disk Size | `var_disk` | Disk size in GB |
| 6 | CPU Cores | `var_cpu` | Number of CPU cores |
| 7 | RAM Size | `var_ram` | RAM size in MiB |
| 8 | Network Bridge | `var_brg` | Network bridge (vmbr0, etc.) |
| 9 | IPv4 Configuration | `var_net`, `var_gateway` | DHCP or static IP with gateway |
| 10 | IPv6 Configuration | `var_ipv6_method` | Auto, DHCP, Static, or None |
| 11 | MTU Size | `var_mtu` | Network MTU (default: 1500) |
| 12 | DNS Search Domain | `var_searchdomain` | DNS search domain |
| 13 | DNS Server | `var_ns` | Custom DNS server IP |
| 14 | MAC Address | `var_mac` | Custom MAC address (auto-generated if empty) |
| 15 | VLAN Tag | `var_vlan` | VLAN tag ID |
| 16 | Tags | `var_tags` | Container tags (comma/semicolon separated) |
| 17 | SSH Settings | `var_ssh` | SSH key selection and root access |
| 18 | FUSE Support | `var_fuse` | Enable FUSE for rclone, mergerfs, AppImage |
| 19 | TUN/TAP Support | `var_tun` | Enable for VPN apps (WireGuard, OpenVPN, Tailscale) |
| 20 | Nesting Support | `var_nesting` | Enable for Docker, LXC in LXC, Podman |
| 21 | GPU Passthrough | `var_gpu` | Auto-detect and pass through Intel/AMD/NVIDIA GPUs |
| 22 | Keyctl Support | `var_keyctl` | Enable for Docker, systemd-networkd |
| 23 | APT Cacher Proxy | `var_apt_cacher`, `var_apt_cacher_ip` | Use apt-cacher-ng for faster downloads |
| 24 | Container Timezone | `var_timezone` | Set timezone (e.g., Europe/Berlin) |
| 25 | Container Protection | `var_protection` | Prevent accidental deletion |
| 26 | Device Node Creation | `var_mknod` | Allow mknod (experimental, kernel 5.3+) |
| 27 | Mount Filesystems | `var_mount_fs` | Allow specific mounts: nfs, cifs, fuse, etc. |
| 28 | Verbose Mode & Confirm | `var_verbose` | Enable verbose output + final confirmation |

## Default Value Inheritance

The wizard inherits defaults from multiple sources:

```text
CT Script (var_*) → default.vars → app.vars → User Input
```

### Example: VPN Container (alpine-wireguard.sh)

```bash
# CT script sets:
var_tun="${var_tun:-1}" # TUN enabled by default

# In Advanced Settings Step 19:
# Dialog shows: "(App default: 1)" and pre-selects "Yes"
```

### Example: Media Server (jellyfin.sh)

```bash
# CT script sets:
var_gpu="${var_gpu:-yes}" # GPU enabled by default

# In Advanced Settings Step 21:
# Dialog shows: "(App default: yes)" and pre-selects "Yes"
```

## Feature Matrix

| Feature | Variable | When to Enable |
| ----------------- | ---------------- | --------------------------------------------------- |
| FUSE | `var_fuse` | rclone, mergerfs, AppImage, SSHFS |
| TUN/TAP | `var_tun` | WireGuard, OpenVPN, Tailscale, VPN containers |
| Nesting | `var_nesting` | Docker, Podman, LXC-in-LXC, systemd-nspawn |
| GPU Passthrough | `var_gpu` | Plex, Jellyfin, Emby, Frigate, Ollama, ComfyUI |
| Keyctl | `var_keyctl` | Docker (unprivileged), systemd-networkd |
| Protection | `var_protection` | Production containers, prevent accidental deletion |
| Mknod | `var_mknod` | Device node creation (experimental) |
| Mount FS | `var_mount_fs` | NFS mounts, CIFS shares, custom filesystems |
| APT Cacher | `var_apt_cacher` | Speed up downloads with local apt-cacher-ng |

## Confirmation Summary

Step 28 displays a comprehensive summary before creation:

```text
Container Type: Unprivileged
Container ID: 100
Hostname: jellyfin

Resources:
Disk: 8 GB
CPU: 2 cores
RAM: 2048 MiB

Network:
Bridge: vmbr0
IPv4: dhcp
IPv6: auto

Features:
FUSE: no | TUN: no
Nesting: Enabled | Keyctl: Disabled
GPU: yes | Protection: No

Advanced:
Timezone: Europe/Berlin
APT Cacher: no
Verbose: no
```

## Usage Examples

### Skip to Advanced Settings

```bash
# Run script, select "Advanced" from menu
bash -c "$(curl -fsSL https://...jellyfin.sh)"
# Then select option 3 "Advanced"
```

### Pre-set Defaults via Environment

```bash
# Set defaults before running
export var_cpu=4
export var_ram=4096
export var_gpu=yes
bash -c "$(curl -fsSL https://...jellyfin.sh)"
# Advanced settings will inherit these values
```

### Non-Interactive with All Options

```bash
# Set all variables for fully automated deployment
export var_unprivileged=1
export var_cpu=2
export var_ram=2048
export var_disk=8
export var_net=dhcp
export var_fuse=no
export var_tun=no
export var_gpu=yes
export var_nesting=1
export var_protection=no
export var_verbose=no
bash -c "$(curl -fsSL https://...jellyfin.sh)"
```

## Notes

- **Cancel at Step 1**: Exits the script entirely
- **Cancel at Steps 2-28**: Goes back to previous step
- **Empty fields**: Use default value
- **Keyctl**: Automatically enabled for unprivileged containers
- **Nesting**: Enabled by default (required for many apps)
41 changes: 30 additions & 11 deletions docs/misc/build.func/BUILD_FUNC_ENVIRONMENT_VARIABLES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,17 +66,36 @@ This document provides a comprehensive reference of all environment variables us

### 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 |
| Variable | Description | Default | Set In | Used In |
| ---------------- | ------------------------------ | ------- | ------------------------------- | ------------------ |
| `var_fuse` | Enable FUSE support | "no" | CT script / Advanced Settings | Container features |
| `var_tun` | Enable TUN/TAP support | "no" | CT script / Advanced Settings | Container features |
| `var_nesting` | Enable nesting support | "1" | CT script / Advanced Settings | Container features |
| `var_keyctl` | Enable keyctl support | "0" | CT script / Advanced Settings | Container features |
| `var_mknod` | Allow device node creation | "0" | CT script / Advanced Settings | Container features |
| `var_mount_fs` | Allowed filesystem mounts | "" | CT script / Advanced Settings | Container features |
| `var_protection` | Enable container protection | "no" | CT script / Advanced Settings | Container creation |
| `var_timezone` | Container timezone | "" | CT script / Advanced Settings | Container creation |
| `var_verbose` | Enable verbose output | "no" | Environment / Advanced Settings | Logging |
| `var_ssh` | Enable SSH key provisioning | "no" | CT script / Advanced Settings | SSH setup |
| `ENABLE_FUSE` | FUSE flag (internal) | "no" | Advanced Settings | Container creation |
| `ENABLE_TUN` | TUN/TAP flag (internal) | "no" | Advanced Settings | Container creation |
| `ENABLE_NESTING` | Nesting flag (internal) | "1" | Advanced Settings | Container creation |
| `ENABLE_KEYCTL` | Keyctl flag (internal) | "0" | Advanced Settings | Container creation |
| `ENABLE_MKNOD` | Mknod flag (internal) | "0" | Advanced Settings | Container creation |
| `PROTECT_CT` | Protection flag (internal) | "no" | Advanced Settings | Container creation |
| `CT_TIMEZONE` | Timezone setting (internal) | "" | Advanced Settings | Container creation |
| `VERBOSE` | Verbose mode flag | "no" | Environment | Logging |
| `SSH` | SSH access flag | "no" | Advanced Settings | SSH setup |

### APT Cacher Configuration

| Variable | Description | Default | Set In | Used In |
| ------------------ | ------------------------ | ------- | ----------------------------- | ------------------- |
| `var_apt_cacher` | Enable APT cacher proxy | "no" | CT script / Advanced Settings | Package management |
| `var_apt_cacher_ip`| APT cacher server IP | "" | CT script / Advanced Settings | Package management |
| `APT_CACHER` | APT cacher flag | "no" | Advanced Settings | Container creation |
| `APT_CACHER_IP` | APT cacher IP (internal) | "" | Advanced Settings | Container creation |

### GPU Passthrough Variables

Expand Down
10 changes: 10 additions & 0 deletions docs/misc/build.func/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,16 @@ This directory contains comprehensive documentation for the `build.func` script,

## Documentation Files

### 🎛️ [BUILD_FUNC_ADVANCED_SETTINGS.md](./BUILD_FUNC_ADVANCED_SETTINGS.md)
Complete reference for the 28-step Advanced Settings wizard, including all configurable options and their inheritance behavior.

**Contents:**
- All 28 wizard steps explained
- Default value inheritance
- Feature matrix (when to enable each feature)
- Confirmation summary format
- Usage examples

### 📊 [BUILD_FUNC_FLOWCHART.md](./BUILD_FUNC_FLOWCHART.md)
Visual ASCII flowchart showing the main execution flow, decision trees, and key decision points in the build.func script.

Expand Down
Loading