Skip to content

Commit bea9a62

Browse files
MickLeskMickLesk
authored
Feature: extend advanced settings with more options & inherit app defaults (#9776)
1 parent 1458aad commit bea9a62

File tree

4 files changed

+512
-60
lines changed

4 files changed

+512
-60
lines changed

‎docs/misc/build.func/BUILD_FUNC_ADVANCED_SETTINGS.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Advanced Settings Wizard Reference
2+
3+
## Overview
4+
5+
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.
6+
7+
## Key Features
8+
9+
- **Inherit App Defaults**: All `var_*` values from CT scripts pre-populate wizard fields
10+
- **Back Navigation**: Press Cancel/Back to return to previous step
11+
- **App Default Hints**: Each dialog shows `(App default: X)` to indicate script defaults
12+
- **Full Customization**: Every configurable option is accessible
13+
14+
## Wizard Steps
15+
16+
| Step | Title | Variable(s) | Description |
17+
| ---- | ------------------------ | --------------------------------- | ----------------------------------------------------- |
18+
| 1 | Container Type | `var_unprivileged` | Privileged (0) or Unprivileged (1) container |
19+
| 2 | Root Password | `var_pw` | Set password or use automatic login |
20+
| 3 | Container ID | `var_ctid` | Unique container ID (auto-suggested) |
21+
| 4 | Hostname | `var_hostname` | Container hostname |
22+
| 5 | Disk Size | `var_disk` | Disk size in GB |
23+
| 6 | CPU Cores | `var_cpu` | Number of CPU cores |
24+
| 7 | RAM Size | `var_ram` | RAM size in MiB |
25+
| 8 | Network Bridge | `var_brg` | Network bridge (vmbr0, etc.) |
26+
| 9 | IPv4 Configuration | `var_net`, `var_gateway` | DHCP or static IP with gateway |
27+
| 10 | IPv6 Configuration | `var_ipv6_method` | Auto, DHCP, Static, or None |
28+
| 11 | MTU Size | `var_mtu` | Network MTU (default: 1500) |
29+
| 12 | DNS Search Domain | `var_searchdomain` | DNS search domain |
30+
| 13 | DNS Server | `var_ns` | Custom DNS server IP |
31+
| 14 | MAC Address | `var_mac` | Custom MAC address (auto-generated if empty) |
32+
| 15 | VLAN Tag | `var_vlan` | VLAN tag ID |
33+
| 16 | Tags | `var_tags` | Container tags (comma/semicolon separated) |
34+
| 17 | SSH Settings | `var_ssh` | SSH key selection and root access |
35+
| 18 | FUSE Support | `var_fuse` | Enable FUSE for rclone, mergerfs, AppImage |
36+
| 19 | TUN/TAP Support | `var_tun` | Enable for VPN apps (WireGuard, OpenVPN, Tailscale) |
37+
| 20 | Nesting Support | `var_nesting` | Enable for Docker, LXC in LXC, Podman |
38+
| 21 | GPU Passthrough | `var_gpu` | Auto-detect and pass through Intel/AMD/NVIDIA GPUs |
39+
| 22 | Keyctl Support | `var_keyctl` | Enable for Docker, systemd-networkd |
40+
| 23 | APT Cacher Proxy | `var_apt_cacher`, `var_apt_cacher_ip` | Use apt-cacher-ng for faster downloads |
41+
| 24 | Container Timezone | `var_timezone` | Set timezone (e.g., Europe/Berlin) |
42+
| 25 | Container Protection | `var_protection` | Prevent accidental deletion |
43+
| 26 | Device Node Creation | `var_mknod` | Allow mknod (experimental, kernel 5.3+) |
44+
| 27 | Mount Filesystems | `var_mount_fs` | Allow specific mounts: nfs, cifs, fuse, etc. |
45+
| 28 | Verbose Mode & Confirm | `var_verbose` | Enable verbose output + final confirmation |
46+
47+
## Default Value Inheritance
48+
49+
The wizard inherits defaults from multiple sources:
50+
51+
```text
52+
CT Script (var_*) → default.vars → app.vars → User Input
53+
```
54+
55+
### Example: VPN Container (alpine-wireguard.sh)
56+
57+
```bash
58+
# CT script sets:
59+
var_tun="${var_tun:-1}" # TUN enabled by default
60+
61+
# In Advanced Settings Step 19:
62+
# Dialog shows: "(App default: 1)" and pre-selects "Yes"
63+
```
64+
65+
### Example: Media Server (jellyfin.sh)
66+
67+
```bash
68+
# CT script sets:
69+
var_gpu="${var_gpu:-yes}" # GPU enabled by default
70+
71+
# In Advanced Settings Step 21:
72+
# Dialog shows: "(App default: yes)" and pre-selects "Yes"
73+
```
74+
75+
## Feature Matrix
76+
77+
| Feature | Variable | When to Enable |
78+
| ----------------- | ---------------- | --------------------------------------------------- |
79+
| FUSE | `var_fuse` | rclone, mergerfs, AppImage, SSHFS |
80+
| TUN/TAP | `var_tun` | WireGuard, OpenVPN, Tailscale, VPN containers |
81+
| Nesting | `var_nesting` | Docker, Podman, LXC-in-LXC, systemd-nspawn |
82+
| GPU Passthrough | `var_gpu` | Plex, Jellyfin, Emby, Frigate, Ollama, ComfyUI |
83+
| Keyctl | `var_keyctl` | Docker (unprivileged), systemd-networkd |
84+
| Protection | `var_protection` | Production containers, prevent accidental deletion |
85+
| Mknod | `var_mknod` | Device node creation (experimental) |
86+
| Mount FS | `var_mount_fs` | NFS mounts, CIFS shares, custom filesystems |
87+
| APT Cacher | `var_apt_cacher` | Speed up downloads with local apt-cacher-ng |
88+
89+
## Confirmation Summary
90+
91+
Step 28 displays a comprehensive summary before creation:
92+
93+
```text
94+
Container Type: Unprivileged
95+
Container ID: 100
96+
Hostname: jellyfin
97+
98+
Resources:
99+
Disk: 8 GB
100+
CPU: 2 cores
101+
RAM: 2048 MiB
102+
103+
Network:
104+
Bridge: vmbr0
105+
IPv4: dhcp
106+
IPv6: auto
107+
108+
Features:
109+
FUSE: no | TUN: no
110+
Nesting: Enabled | Keyctl: Disabled
111+
GPU: yes | Protection: No
112+
113+
Advanced:
114+
Timezone: Europe/Berlin
115+
APT Cacher: no
116+
Verbose: no
117+
```
118+
119+
## Usage Examples
120+
121+
### Skip to Advanced Settings
122+
123+
```bash
124+
# Run script, select "Advanced" from menu
125+
bash -c "$(curl -fsSL https://...jellyfin.sh)"
126+
# Then select option 3 "Advanced"
127+
```
128+
129+
### Pre-set Defaults via Environment
130+
131+
```bash
132+
# Set defaults before running
133+
export var_cpu=4
134+
export var_ram=4096
135+
export var_gpu=yes
136+
bash -c "$(curl -fsSL https://...jellyfin.sh)"
137+
# Advanced settings will inherit these values
138+
```
139+
140+
### Non-Interactive with All Options
141+
142+
```bash
143+
# Set all variables for fully automated deployment
144+
export var_unprivileged=1
145+
export var_cpu=2
146+
export var_ram=2048
147+
export var_disk=8
148+
export var_net=dhcp
149+
export var_fuse=no
150+
export var_tun=no
151+
export var_gpu=yes
152+
export var_nesting=1
153+
export var_protection=no
154+
export var_verbose=no
155+
bash -c "$(curl -fsSL https://...jellyfin.sh)"
156+
```
157+
158+
## Notes
159+
160+
- **Cancel at Step 1**: Exits the script entirely
161+
- **Cancel at Steps 2-28**: Goes back to previous step
162+
- **Empty fields**: Use default value
163+
- **Keyctl**: Automatically enabled for unprivileged containers
164+
- **Nesting**: Enabled by default (required for many apps)

‎docs/misc/build.func/BUILD_FUNC_ENVIRONMENT_VARIABLES.md‎

Lines changed: 30 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -66,17 +66,36 @@ This document provides a comprehensive reference of all environment variables us
6666

6767
### Feature Flags
6868

69-
| Variable | Description | Default | Set In | Used In |
70-
| --------------------- | --------------------------- | ------- | --------------- | ------------------ |
71-
| `ENABLE_FUSE` | Enable FUSE support | "true" | base_settings() | Container features |
72-
| `ENABLE_TUN` | Enable TUN/TAP support | "true" | base_settings() | Container features |
73-
| `ENABLE_KEYCTL` | Enable keyctl support | "true" | base_settings() | Container features |
74-
| `ENABLE_MOUNT` | Enable mount support | "true" | base_settings() | Container features |
75-
| `ENABLE_NESTING` | Enable nesting support | "false" | base_settings() | Container features |
76-
| `ENABLE_PRIVILEGED` | Enable privileged mode | "false" | base_settings() | Container features |
77-
| `ENABLE_UNPRIVILEGED` | Enable unprivileged mode | "true" | base_settings() | Container features |
78-
| `VERBOSE` | Enable verbose output | "false" | Environment | Logging |
79-
| `SSH` | Enable SSH key provisioning | "true" | base_settings() | SSH setup |
69+
| Variable | Description | Default | Set In | Used In |
70+
| ---------------- | ------------------------------ | ------- | ------------------------------- | ------------------ |
71+
| `var_fuse` | Enable FUSE support | "no" | CT script / Advanced Settings | Container features |
72+
| `var_tun` | Enable TUN/TAP support | "no" | CT script / Advanced Settings | Container features |
73+
| `var_nesting` | Enable nesting support | "1" | CT script / Advanced Settings | Container features |
74+
| `var_keyctl` | Enable keyctl support | "0" | CT script / Advanced Settings | Container features |
75+
| `var_mknod` | Allow device node creation | "0" | CT script / Advanced Settings | Container features |
76+
| `var_mount_fs` | Allowed filesystem mounts | "" | CT script / Advanced Settings | Container features |
77+
| `var_protection` | Enable container protection | "no" | CT script / Advanced Settings | Container creation |
78+
| `var_timezone` | Container timezone | "" | CT script / Advanced Settings | Container creation |
79+
| `var_verbose` | Enable verbose output | "no" | Environment / Advanced Settings | Logging |
80+
| `var_ssh` | Enable SSH key provisioning | "no" | CT script / Advanced Settings | SSH setup |
81+
| `ENABLE_FUSE` | FUSE flag (internal) | "no" | Advanced Settings | Container creation |
82+
| `ENABLE_TUN` | TUN/TAP flag (internal) | "no" | Advanced Settings | Container creation |
83+
| `ENABLE_NESTING` | Nesting flag (internal) | "1" | Advanced Settings | Container creation |
84+
| `ENABLE_KEYCTL` | Keyctl flag (internal) | "0" | Advanced Settings | Container creation |
85+
| `ENABLE_MKNOD` | Mknod flag (internal) | "0" | Advanced Settings | Container creation |
86+
| `PROTECT_CT` | Protection flag (internal) | "no" | Advanced Settings | Container creation |
87+
| `CT_TIMEZONE` | Timezone setting (internal) | "" | Advanced Settings | Container creation |
88+
| `VERBOSE` | Verbose mode flag | "no" | Environment | Logging |
89+
| `SSH` | SSH access flag | "no" | Advanced Settings | SSH setup |
90+
91+
### APT Cacher Configuration
92+
93+
| Variable | Description | Default | Set In | Used In |
94+
| ------------------ | ------------------------ | ------- | ----------------------------- | ------------------- |
95+
| `var_apt_cacher` | Enable APT cacher proxy | "no" | CT script / Advanced Settings | Package management |
96+
| `var_apt_cacher_ip`| APT cacher server IP | "" | CT script / Advanced Settings | Package management |
97+
| `APT_CACHER` | APT cacher flag | "no" | Advanced Settings | Container creation |
98+
| `APT_CACHER_IP` | APT cacher IP (internal) | "" | Advanced Settings | Container creation |
8099

81100
### GPU Passthrough Variables
82101

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

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,16 @@ This directory contains comprehensive documentation for the `build.func` script,
66

77
## Documentation Files
88

9+
### 🎛️ [BUILD_FUNC_ADVANCED_SETTINGS.md](./BUILD_FUNC_ADVANCED_SETTINGS.md)
10+
Complete reference for the 28-step Advanced Settings wizard, including all configurable options and their inheritance behavior.
11+
12+
**Contents:**
13+
- All 28 wizard steps explained
14+
- Default value inheritance
15+
- Feature matrix (when to enable each feature)
16+
- Confirmation summary format
17+
- Usage examples
18+
919
### 📊 [BUILD_FUNC_FLOWCHART.md](./BUILD_FUNC_FLOWCHART.md)
1020
Visual ASCII flowchart showing the main execution flow, decision trees, and key decision points in the build.func script.
1121

0 commit comments

Comments
 (0)