From fab29de5987c930bcf55f49d6ed4a3af9f9d5ec5 Mon Sep 17 00:00:00 2001 From: Jerod Fritz Date: Thu, 4 Dec 2025 16:13:13 -0500 Subject: [PATCH 1/6] new macros IF SERVER_HOST, APP_INSTALLED documented --- .../apps/install-scripts/reference/macros.md | 59 ++++++++ .../apps/install-scripts/reference/schema.md | 130 +++++++----------- 2 files changed, 108 insertions(+), 81 deletions(-) diff --git a/docs/features/apps/install-scripts/reference/macros.md b/docs/features/apps/install-scripts/reference/macros.md index 7a6a01b0..54f8f86b 100644 --- a/docs/features/apps/install-scripts/reference/macros.md +++ b/docs/features/apps/install-scripts/reference/macros.md @@ -47,6 +47,65 @@ Resolves to the server's LAN IP address. Useful for constructing URLs that point ] ``` +## `$SERVER_HOST_ID` +Resolves to the server's unique host ID. This is particularly useful for constructing HexOS Tunnels (e.g., `https://.direct.hexos.com`) for remote tunneled access to your apps and services. + +**Example:** +```json +{ + "value": "https://$SERVER_HOST_ID.direct.hexos.com" +} +``` + +## `$APP_INSTALLED(appName)` +Checks if a specific app is installed on the TrueNAS system. Returns `true` if installed, `false` otherwise. The check is case-insensitive. + +**Example:** +```json +"$APP_INSTALLED(qbittorrent)" // Returns "true" or "false" +``` + +## `$QUESTION(key)` +Accesses user responses from installation questions. The value is replaced with the user's response, which can be a boolean, string, number, or empty. When used in conditional expressions, values are converted appropriately: +- Boolean values become `"true"` or `"false"` +- Empty/null values become `"false"` +- String values are quoted unless they're "true" or "false" +- Numbers are converted to strings + +**Examples:** +```json +"enabled": "$QUESTION(enable_feature)" // Direct value replacement +"$IF($QUESTION(use_ssl), \"https\", \"http\")" // Boolean check +"$IF($QUESTION(port) != \"\", $QUESTION(port), \"8080\")" // Default value +``` + +## `$IF(condition, trueValue, [falseValue])` +Provides conditional logic in install scripts. Evaluates a condition and returns different values based on the result. + +**Syntax Variations:** +1. **Basic if/else**: `$IF(condition, trueValue, falseValue)` +2. **If only**: `$IF(condition, trueValue)` - Returns empty string if false +3. **Multiple conditions with AND**: `$IF(['condition1', 'condition2'], trueValue, falseValue, 'AND')` +4. **Multiple conditions with OR**: `$IF(['condition1', 'condition2'], trueValue, falseValue, 'OR')` + +**Supported Conditions:** +- Boolean literals: `true`, `false` +- Negation: `!condition` +- App installation checks: `$APP_INSTALLED(appName)` +- Question responses: `$QUESTION(key)` +- Equality comparison: `value1 == value2` +- Inequality comparison: `value1 != value2` + +**Example:** +```json +"additional_storage": [ + "$IF($APP_INSTALLED(qbittorrent), '$MOUNTED_HOST_PATH($LOCATION(Downloads)/qbittorrent, /downloads)')", + "$IF($QUESTION(use_qbittorent), '$MOUNTED_HOST_PATH($LOCATION(Downloads)/qbittorent, /downloads/transmission)')", + ... +] +``` +*Conditionally mounts download folders based on installed apps and user preferences* + #### `$MEMORY(percentage, minimum_mb)` Dynamically allocates memory based on system resources. Takes the higher value between the percentage of system memory and the minimum specified in MB. diff --git a/docs/features/apps/install-scripts/reference/schema.md b/docs/features/apps/install-scripts/reference/schema.md index 2f4edf6c..76c6af55 100644 --- a/docs/features/apps/install-scripts/reference/schema.md +++ b/docs/features/apps/install-scripts/reference/schema.md @@ -1,94 +1,51 @@ ### Install Script Schema -Install scripts are JSON objects with the following structure: +Install scripts are JSON objects with the following structure. Scripts can use various macros (template variables) that are dynamically replaced during processing. ## Root Properties -- **`version`** (required): Schema version. Must be `1` or `2`. -- **`requirements`** (optional): System requirements that are validated before installation -- **`installation_questions`** (optional, introduced in version 2): Array of questions to ask the user during installation +- **`version`** (required): Schema version. Must be `3` or higher (currently latest supported version). +- **`script`** (required): Metadata about the install script itself + - **`version`** (required): Semantic version of this install script (e.g., "1.0.0", "2.1.3") + - **`updateCompatibility`** (optional): Minimum script version this can update from (e.g., "1.0.0" means it can update any script version 1.0.0 or higher) + - **`changeLog`** (optional): Description of changes in this version of the script +- **`requirements`** (required): System requirements that are validated before installation +- **`installation_questions`** (optional): Array of questions to ask the user during installation - **`ensure_directories_exists`** (optional): Array of directories to create before installation - **`ensure_permissions_exists`** (optional): Array of permission modifications for specific paths - **`app_values`** (required): Configuration object passed directly to TrueNAS API +## Available Macros + +Install scripts support various macros that are replaced dynamically during script processing: + +### Basic Macros +- **`$SERVER_LAN_IP`**: Server's LAN IP address +- **`$SERVER_HOST_ID`**: Server's unique host ID +- **`$LOCATION(locationId)`**: Resolves to configured location path +- **`$RANDOM_STRING(length)`**: Generates random alphanumeric string +- **`$MEMORY(percentage, minimum_mb)`**: Calculates memory allocation +- **`$HOST_PATH(path)`**: Creates host path configuration object +- **`$MOUNTED_HOST_PATH(path, mount_point)`**: Creates mounted host path configuration + +### Conditional Macros +- **`$APP_INSTALLED(appName)`**: Returns "true" or "false" if app is installed +- **`$QUESTION(key)`**: References user's response to installation question +- **`$IF(condition, trueValue, [falseValue])`**: Conditional logic with support for: + - Boolean literals: `true`, `false` + - Negation: `!condition` + - App checks: `$APP_INSTALLED(appName)` + - Question values: `$QUESTION(key)` + - Equality: `value1 == value2` + - Inequality: `value1 != value2` + - AND logic: `$IF(["condition1", "condition2"], trueValue, falseValue, "AND")` + - OR logic: `$IF(["condition1", "condition2"], trueValue, falseValue, "OR")` + +For detailed macro documentation and examples, see the [Macros Reference](/features/apps/install-scripts/reference/macros). + ## Example Structure -```json -{ - "version": 2, - "requirements": { - "locations": ["ApplicationsPerformance", "Photos"], - "specifications": ["2CORE", "200MB"], - "permissions": ["READ_WRITE_LOCATIONS"], - "ports": [] - }, - "installation_questions": [ - { - "question": "Database Password", - "description": "A secure password for the PostgreSQL database.", - "type": "text", - "key": "db_password", - "required": true, - "default": "$RANDOM_STRING(16)" - }, - { - "question": "Enable GPU acceleration for machine learning?", - "description": "GPU acceleration significantly improves photo recognition speed but requires compatible hardware.", - "type": "select", - "key": "gpu_passthrough", - "required": true, - "options": [ - { - "text": "Yes - Use GPU for faster photo recognition", - "value": true - }, - { - "text": "No - Use CPU only", - "value": false - } - ], - "default": false - }, - { - "question": "Web Port", - "description": "The port number where the web interface will be accessible.", - "placeholder": "2283", - "type": "number", - "key": "web_port", - "required": false, - "default": 2283 - } - ], - "ensure_directories_exists": [ - "/path/to/directory", - { - "path": "/path/with/options", - "network_share": true, - "posix": true - } - ], - "ensure_permissions_exists": [ - { - "path": "/path/to/set/permissions", - "username": "netdata", - "access": "read", - "posix": { "groupname": "docker" } - } - ], - "app_values": { - "network": { - "web_port": { - "bind_mode": "published", - "port_number": "$QUESTION(web_port)" - } - }, - "resources": { - "gpus": { - "use_all_gpus": "$QUESTION(gpu_passthrough)" - } - } - } -} -``` + +For complete, working examples of install scripts, please refer to the [curated install scripts](/features/apps/install-scripts/curated/). These production-ready scripts demonstrate best practices and real-world usage patterns for popular applications like Plex, Jellyfin, Immich, and more. ## Requirements @@ -273,6 +230,10 @@ Reference question responses in your `app_values` using the `$QUESTION(key)` syn } ``` +**Using Questions in Conditionals:** + +Question responses can be used in conditional logic with the `$IF` macro. See the [$IF macro documentation](/features/apps/install-scripts/reference/macros#if-condition-truevalue-falsevalue) for examples of using questions in conditional expressions. + ## Directory Creation - **String format**: Simple path string - **Object format**: @@ -289,3 +250,10 @@ Required for apps that need specific user/group permissions (like PostgreSQL). ## App Values This object is passed directly to TrueNAS's app installation API. The structure varies by application and corresponds to the app's configuration schema in the [TrueNAS apps repository](https://github.com/truenas/apps). For example, you can see Plex's schema for the `storage` property [here](https://github.com/truenas/apps/blob/1d2a6e9811f9af2ceae6529cc094a432a7da4e96/trains/stable/plex/app_versions.json#L422). + +### Conditional Configuration + +Install scripts support conditional logic to customize app configuration based on: +- Other installed apps using [`$APP_INSTALLED(appName)`](/features/apps/install-scripts/reference/macros#app_installedappname) +- User responses to installation questions using [`$QUESTION(key)`](/features/apps/install-scripts/reference/macros#questionkey) +- Complex conditions using the [`$IF`](/features/apps/install-scripts/reference/macros#if-condition-truevalue-falsevalue) macro From 625cbd83c64b985448a9b55ac382d07c3d70ff79 Mon Sep 17 00:00:00 2001 From: Jerod Fritz Date: Thu, 4 Dec 2025 16:13:24 -0500 Subject: [PATCH 2/6] updates apps for v3 --- docs/public/install-scripts/home-assistant.json | 8 ++++++-- docs/public/install-scripts/immich.json | 8 ++++++-- docs/public/install-scripts/jellyfin.json | 8 ++++++-- docs/public/install-scripts/plex.json | 12 +++++++++++- docs/public/install-scripts/prowlarr.json | 12 +++++++++++- docs/public/install-scripts/qbittorrent.json | 8 ++++++-- docs/public/install-scripts/radarr.json | 12 +++++++++++- docs/public/install-scripts/sonarr.json | 12 +++++++++++- 8 files changed, 68 insertions(+), 12 deletions(-) diff --git a/docs/public/install-scripts/home-assistant.json b/docs/public/install-scripts/home-assistant.json index 3157d045..369bd90f 100644 --- a/docs/public/install-scripts/home-assistant.json +++ b/docs/public/install-scripts/home-assistant.json @@ -1,10 +1,14 @@ { - "version": 1, + "version": 3, + "script": { + "version": "1.0.0", + "changeLog": "Upgraded Home Assistant install script to be compatible with latest HexOS script changes" + }, "requirements": { "locations": ["ApplicationsPerformance", "Media"], "specifications": ["2CORE", "200MB"], "permissions": ["READ_WRITE_LOCATIONS"], - "ports": [] + "ports": [8123] }, "ensure_directories_exists": [ { diff --git a/docs/public/install-scripts/immich.json b/docs/public/install-scripts/immich.json index fb75ca5f..9e6c62a7 100644 --- a/docs/public/install-scripts/immich.json +++ b/docs/public/install-scripts/immich.json @@ -1,10 +1,14 @@ { - "version": 1, + "version": 3, + "script": { + "version": "1.0.0", + "changeLog": "Upgraded Immich install script to be compatible with latest HexOS script changes" + }, "requirements": { "locations": ["ApplicationsPerformance", "Photos"], "specifications": ["2CORE", "200MB"], "permissions": ["READ_WRITE_LOCATIONS"], - "ports": [] + "ports": [2283] }, "ensure_directories_exists": [ { diff --git a/docs/public/install-scripts/jellyfin.json b/docs/public/install-scripts/jellyfin.json index e22b02b2..7dc08aad 100644 --- a/docs/public/install-scripts/jellyfin.json +++ b/docs/public/install-scripts/jellyfin.json @@ -1,10 +1,14 @@ { - "version": 1, + "version": 3, + "script": { + "version": "1.0.0", + "changeLog": "Upgraded Jellyfin install script to be compatible with latest HexOS script changes" + }, "requirements": { "locations": ["ApplicationsPerformance", "ApplicationsCapacity", "Media", "Photos", "Music", "Movies", "Shows", "Videos"], "specifications": ["2CORE", "200MB"], "permissions": ["READ_WRITE_LOCATIONS"], - "ports": [] + "ports": [8096, 8920] }, "ensure_directories_exists": [ { diff --git a/docs/public/install-scripts/plex.json b/docs/public/install-scripts/plex.json index d499ef4d..f54fc79a 100644 --- a/docs/public/install-scripts/plex.json +++ b/docs/public/install-scripts/plex.json @@ -1,5 +1,9 @@ { - "version": 2, + "version": 3, + "script": { + "version": "1.0.0", + "changeLog": "Upgraded Plex install script to be compatible with latest HexOS script changes" + }, "installation_questions": [ { "question": "Claim Token (Optional)", @@ -29,6 +33,12 @@ "default": "image" } ], + "requirements": { + "locations": ["ApplicationsPerformance", "ApplicationsCapacity", "Media", "Photos", "Music", "Movies", "Shows", "Videos"], + "specifications": ["2CORE", "200MB"], + "permissions": ["READ_WRITE_LOCATIONS"], + "ports": [32400] + }, "ensure_directories_exists": [ { "path": "$LOCATION(ApplicationsPerformance)", diff --git a/docs/public/install-scripts/prowlarr.json b/docs/public/install-scripts/prowlarr.json index 30b49088..382c4263 100644 --- a/docs/public/install-scripts/prowlarr.json +++ b/docs/public/install-scripts/prowlarr.json @@ -1,5 +1,15 @@ { - "version": 1, + "version": 3, + "script": { + "version": "1.0.0", + "changeLog": "Upgraded Prowlarr install script to be compatible with latest HexOS script changes" + }, + "requirements": { + "locations": ["ApplicationsPerformance"], + "specifications": ["2CORE", "200MB"], + "permissions": ["READ_WRITE_LOCATIONS"], + "ports": [9696] + }, "ensure_directories_exists": [ { "path": "$LOCATION(ApplicationsPerformance)", diff --git a/docs/public/install-scripts/qbittorrent.json b/docs/public/install-scripts/qbittorrent.json index f06a01d1..db383af9 100644 --- a/docs/public/install-scripts/qbittorrent.json +++ b/docs/public/install-scripts/qbittorrent.json @@ -1,10 +1,14 @@ { - "version": 1, + "version": 3, + "script": { + "version": "1.0.0", + "changeLog": "Upgraded qBittorrent install script to be compatible with latest HexOS script changes" + }, "requirements": { "locations": ["ApplicationsPerformance", "ApplicationsCapacity", "Downloads"], "specifications": ["2CORE", "200MB"], "permissions": ["READ_WRITE_LOCATIONS"], - "ports": [] + "ports": [8080, 6881] }, "ensure_directories_exists": [ { diff --git a/docs/public/install-scripts/radarr.json b/docs/public/install-scripts/radarr.json index 18ca9915..f0d61b5b 100644 --- a/docs/public/install-scripts/radarr.json +++ b/docs/public/install-scripts/radarr.json @@ -1,5 +1,15 @@ { - "version": 1, + "version": 3, + "script": { + "version": "1.0.0", + "changeLog": "Upgraded Radarr install script to be compatible with latest HexOS script changes" + }, + "requirements": { + "locations": ["ApplicationsPerformance", "ApplicationsCapacity", "Downloads", "Movies"], + "specifications": ["2CORE", "200MB"], + "permissions": ["READ_WRITE_LOCATIONS"], + "ports": [7878] + }, "ensure_directories_exists": [ { "path": "$LOCATION(ApplicationsPerformance)", diff --git a/docs/public/install-scripts/sonarr.json b/docs/public/install-scripts/sonarr.json index 77ade899..3d35511f 100644 --- a/docs/public/install-scripts/sonarr.json +++ b/docs/public/install-scripts/sonarr.json @@ -1,5 +1,15 @@ { - "version": 1, + "version": 3, + "script": { + "version": "1.0.0", + "changeLog": "Upgraded Sonarr install script to be compatible with latest HexOS script changes" + }, + "requirements": { + "locations": ["ApplicationsPerformance", "ApplicationsCapacity", "Downloads", "Shows"], + "specifications": ["2CORE", "200MB"], + "permissions": ["READ_WRITE_LOCATIONS"], + "ports": [8989] + }, "ensure_directories_exists": [ { "path": "$LOCATION(ApplicationsPerformance)", From 27cfd65d2520418ed4278a36b8e19f0dbefd0124 Mon Sep 17 00:00:00 2001 From: Jerod Fritz Date: Tue, 9 Dec 2025 20:09:09 -0500 Subject: [PATCH 3/6] $GPU_CONFIG() schema usage documentation and other misc changes --- .../apps/install-scripts/curated/index.md | 16 +++++----- .../apps/install-scripts/reference/macros.md | 31 +++++++++++++++++++ .../apps/install-scripts/reference/schema.md | 2 +- 3 files changed, 40 insertions(+), 9 deletions(-) diff --git a/docs/features/apps/install-scripts/curated/index.md b/docs/features/apps/install-scripts/curated/index.md index ee35e328..ed499566 100644 --- a/docs/features/apps/install-scripts/curated/index.md +++ b/docs/features/apps/install-scripts/curated/index.md @@ -3,12 +3,12 @@ | App | Download | Size | Last Modified | |---|---|---:|---| -| `home-assistant` | [home-assistant.json](/install-scripts/home-assistant.json) | 1.4 KB | 2025-11-17 | -| `immich` | [immich.json](/install-scripts/immich.json) | 1.6 KB | 2025-11-17 | -| `jellyfin` | [jellyfin.json](/install-scripts/jellyfin.json) | 2.1 KB | 2025-11-17 | -| `plex` | [plex.json](/install-scripts/plex.json) | 3.0 KB | 2025-11-22 | -| `prowlarr` | [prowlarr.json](/install-scripts/prowlarr.json) | 443 B | 2025-11-21 | -| `qbittorrent` | [qbittorrent.json](/install-scripts/qbittorrent.json) | 881 B | 2025-11-21 | -| `radarr` | [radarr.json](/install-scripts/radarr.json) | 904 B | 2025-11-21 | -| `sonarr` | [sonarr.json](/install-scripts/sonarr.json) | 901 B | 2025-11-21 | +| `home-assistant` | [home-assistant.json](/install-scripts/home-assistant.json) | 1.6 KB | 2025-12-04 | +| `immich` | [immich.json](/install-scripts/immich.json) | 1.7 KB | 2025-12-04 | +| `jellyfin` | [jellyfin.json](/install-scripts/jellyfin.json) | 2.3 KB | 2025-12-04 | +| `plex` | [plex.json](/install-scripts/plex.json) | 3.4 KB | 2025-12-04 | +| `prowlarr` | [prowlarr.json](/install-scripts/prowlarr.json) | 766 B | 2025-12-04 | +| `qbittorrent` | [qbittorrent.json](/install-scripts/qbittorrent.json) | 1.0 KB | 2025-12-04 | +| `radarr` | [radarr.json](/install-scripts/radarr.json) | 1.2 KB | 2025-12-04 | +| `sonarr` | [sonarr.json](/install-scripts/sonarr.json) | 1.2 KB | 2025-12-04 | diff --git a/docs/features/apps/install-scripts/reference/macros.md b/docs/features/apps/install-scripts/reference/macros.md index 54f8f86b..6110dcf8 100644 --- a/docs/features/apps/install-scripts/reference/macros.md +++ b/docs/features/apps/install-scripts/reference/macros.md @@ -79,6 +79,37 @@ Accesses user responses from installation questions. The value is replaced with "$IF($QUESTION(port) != \"\", $QUESTION(port), \"8080\")" // Default value ``` +## `$GPU_CONFIG()` +Automatically configures GPU resources for applications. Detects Intel, AMD, and NVIDIA GPUs and generates the appropriate TrueNAS GPU configuration. + +**Behavior:** +- **No GPUs**: Returns `{"use_all_gpus": false}` +- **Intel/AMD**: Returns `{"use_all_gpus": true}` +- **NVIDIA**: Configures individual GPUs with UUIDs (requires drivers) + +**Example:** +```json +"resources": { + "gpus": "$GPU_CONFIG()" +} +``` + +**With conditional:** +```json +"gpus": "$IF($QUESTION(enable_gpu), '$GPU_CONFIG()', {'use_all_gpus': false})" +``` + +**Use Cases:** Media transcoding (Plex, Jellyfin), AI/ML apps (Ollama, Immich), video processing etc. + +**NVIDIA Driver Update Steps:** +NVIDIA drivers were installed already if this was a fresh install, however if this system was adopted or for whatever reason they require manual updating of the drivers from within the TrueNAS ui they can perform the following: + +1. Apps → Settings (gear icon) → Advanced Settings +2. Toggle "Enable GPU Support" or "NVIDIA Runtime" OFF → Save +3. Wait 10-30 seconds +4. Toggle back ON → Save +5. This triggers a `docker.update` with latest compatible NVIDIA drivers + ## `$IF(condition, trueValue, [falseValue])` Provides conditional logic in install scripts. Evaluates a condition and returns different values based on the result. diff --git a/docs/features/apps/install-scripts/reference/schema.md b/docs/features/apps/install-scripts/reference/schema.md index 76c6af55..e9031df8 100644 --- a/docs/features/apps/install-scripts/reference/schema.md +++ b/docs/features/apps/install-scripts/reference/schema.md @@ -7,7 +7,7 @@ Install scripts are JSON objects with the following structure. Scripts can use v - **`version`** (required): Schema version. Must be `3` or higher (currently latest supported version). - **`script`** (required): Metadata about the install script itself - **`version`** (required): Semantic version of this install script (e.g., "1.0.0", "2.1.3") - - **`updateCompatibility`** (optional): Minimum script version this can update from (e.g., "1.0.0" means it can update any script version 1.0.0 or higher) + - **`updateCompatibility`** (optional): Semver range expression defining which script versions can update to this version (e.g., ">=1.0.0" allows updates from any version 1.0.0 or higher, "^2.0.0" allows updates from 2.x.x versions). Supports all [semver range syntax](https://www.npmjs.com/package/semver#ranges) including `>=`, `>`, `<`, `<=`, `^`, `~`, and complex ranges like `">=1.0.0 <3.0.0"` - **`changeLog`** (optional): Description of changes in this version of the script - **`requirements`** (required): System requirements that are validated before installation - **`installation_questions`** (optional): Array of questions to ask the user during installation From 6b57927d72361045f97e34631a4b3af3c424c8a7 Mon Sep 17 00:00:00 2001 From: Jerod Fritz Date: Wed, 10 Dec 2025 12:49:13 -0500 Subject: [PATCH 4/6] More examples of the results of $GPU_CONFIG macro --- .../apps/install-scripts/reference/macros.md | 93 +++++++++++++++++-- 1 file changed, 83 insertions(+), 10 deletions(-) diff --git a/docs/features/apps/install-scripts/reference/macros.md b/docs/features/apps/install-scripts/reference/macros.md index 6110dcf8..1af98dae 100644 --- a/docs/features/apps/install-scripts/reference/macros.md +++ b/docs/features/apps/install-scripts/reference/macros.md @@ -80,26 +80,98 @@ Accesses user responses from installation questions. The value is replaced with ``` ## `$GPU_CONFIG()` -Automatically configures GPU resources for applications. Detects Intel, AMD, and NVIDIA GPUs and generates the appropriate TrueNAS GPU configuration. +Automatically detects and configures GPU resources for applications. The macro queries the system's available GPUs and generates the appropriate TrueNAS GPU configuration object. -**Behavior:** -- **No GPUs**: Returns `{"use_all_gpus": false}` -- **Intel/AMD**: Returns `{"use_all_gpus": true}` -- **NVIDIA**: Configures individual GPUs with UUIDs (requires drivers) - -**Example:** +**Basic Usage:** ```json "resources": { "gpus": "$GPU_CONFIG()" } ``` -**With conditional:** +**Conditional Usage:** ```json "gpus": "$IF($QUESTION(enable_gpu), '$GPU_CONFIG()', {'use_all_gpus': false})" ``` -**Use Cases:** Media transcoding (Plex, Jellyfin), AI/ML apps (Ollama, Immich), video processing etc. +**Detected Configurations & Expanded Values:** + +**No GPU detected:** +```json +// System has no GPUs +"$GPU_CONFIG()" → {"use_all_gpus": false} +``` + +**Intel integrated GPU detected:** +```json +// System has Intel UHD Graphics 770 +"$GPU_CONFIG()" → {"use_all_gpus": true} +``` + +**AMD GPU detected:** +```json +// System has AMD Radeon RX 6700 XT +"$GPU_CONFIG()" → {"use_all_gpus": true} +``` + +**Single NVIDIA GPU detected (with drivers):** +```json +// System has NVIDIA RTX 4090 +"$GPU_CONFIG()" → { + "use_all_gpus": true, + "nvidia_gpu_selection": { + "0000:01:00.0": { + "use_gpu": true, + "uuid": "GPU-8a5f3c21-b4e9-4d72-a123-456789abcdef" + } + } +} +``` + +**Multiple NVIDIA GPUs detected (with drivers):** +```json +// System has 2x NVIDIA RTX A4000 +"$GPU_CONFIG()" → { + "use_all_gpus": true, + "nvidia_gpu_selection": { + "0000:01:00.0": { + "use_gpu": true, + "uuid": "GPU-1a2b3c4d-5e6f-7890-abcd-ef1234567890" + }, + "0000:02:00.0": { + "use_gpu": true, + "uuid": "GPU-9f8e7d6c-5b4a-3210-fedc-ba0987654321" + } + } +} +``` + +**Mixed GPUs (Intel + NVIDIA with drivers):** +```json +// System has Intel UHD 770 + NVIDIA RTX 3060 +"$GPU_CONFIG()" → { + "use_all_gpus": true, + "nvidia_gpu_selection": { + "0000:03:00.0": { + "use_gpu": true, + "uuid": "GPU-7c8d9e0f-1a2b-3c4d-5e6f-789012345678" + } + } +} +``` + +**NVIDIA GPU without drivers (falls back to disabled):** +```json +// System has NVIDIA GPU but drivers not installed +"$GPU_CONFIG()" → {"use_all_gpus": false} +``` + +**Common Use Cases:** +- **Media Servers**: Plex, Jellyfin, Emby (hardware transcoding) +- **AI/ML Applications**: Ollama, Stable Diffusion, ComfyUI +- **Photo Management**: Immich (ML face detection) +- **Video Processing**: Handbrake, FFmpeg-based apps +- **Game Streaming**: Sunshine, Steam Link **NVIDIA Driver Update Steps:** NVIDIA drivers were installed already if this was a fresh install, however if this system was adopted or for whatever reason they require manual updating of the drivers from within the TrueNAS ui they can perform the following: @@ -131,7 +203,8 @@ Provides conditional logic in install scripts. Evaluates a condition and returns ```json "additional_storage": [ "$IF($APP_INSTALLED(qbittorrent), '$MOUNTED_HOST_PATH($LOCATION(Downloads)/qbittorrent, /downloads)')", - "$IF($QUESTION(use_qbittorent), '$MOUNTED_HOST_PATH($LOCATION(Downloads)/qbittorent, /downloads/transmission)')", + "$IF($APP_INSTALLED(sabnzbd), '$MOUNTED_HOST_PATH($LOCATION(Downloads)/sabnzbd, /downloads)')", + "$IF($QUESTION(use_qbittorent), '$MOUNTED_HOST_PATH($LOCATION(Downloads)/qbittorent, /downloads/qbittorent)')", ... ] ``` From d5afa14f67f64e86fa25cf0ffaadd24151161f84 Mon Sep 17 00:00:00 2001 From: Jerod Fritz Date: Thu, 11 Dec 2025 21:30:51 -0500 Subject: [PATCH 5/6] $GPU_CONFIG added to existing install scripts --- docs/public/install-scripts/immich.json | 4 +--- docs/public/install-scripts/jellyfin.json | 4 +--- docs/public/install-scripts/plex.json | 4 +--- 3 files changed, 3 insertions(+), 9 deletions(-) diff --git a/docs/public/install-scripts/immich.json b/docs/public/install-scripts/immich.json index 9e6c62a7..d5262522 100644 --- a/docs/public/install-scripts/immich.json +++ b/docs/public/install-scripts/immich.json @@ -65,9 +65,7 @@ "cpus": 2, "memory": "$MEMORY(10%, 4096)" }, - "gpus": { - "use_all_gpus": true - } + "gpus": "$GPU_CONFIG()" } } } \ No newline at end of file diff --git a/docs/public/install-scripts/jellyfin.json b/docs/public/install-scripts/jellyfin.json index 7dc08aad..a3b81f7a 100644 --- a/docs/public/install-scripts/jellyfin.json +++ b/docs/public/install-scripts/jellyfin.json @@ -76,9 +76,7 @@ "cpus": 2, "memory": "$MEMORY(10%, 4096)" }, - "gpus": { - "use_all_gpus": true - } + "gpus": "$GPU_CONFIG()" } } } \ No newline at end of file diff --git a/docs/public/install-scripts/plex.json b/docs/public/install-scripts/plex.json index f54fc79a..de8879d0 100644 --- a/docs/public/install-scripts/plex.json +++ b/docs/public/install-scripts/plex.json @@ -114,9 +114,7 @@ "cpus": 2, "memory": "$MEMORY(10%, 2048)" }, - "gpus": { - "use_all_gpus": true - } + "gpus": "$GPU_CONFIG()" } } } \ No newline at end of file From b4e620b87ae5f0b61e242c35a828ee6e08417bb6 Mon Sep 17 00:00:00 2001 From: Jerod Fritz Date: Tue, 16 Dec 2025 10:15:03 -0500 Subject: [PATCH 6/6] ran gen:all --- docs/features/apps/install-scripts/curated/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/features/apps/install-scripts/curated/index.md b/docs/features/apps/install-scripts/curated/index.md index ed499566..510e03e8 100644 --- a/docs/features/apps/install-scripts/curated/index.md +++ b/docs/features/apps/install-scripts/curated/index.md @@ -4,9 +4,9 @@ | App | Download | Size | Last Modified | |---|---|---:|---| | `home-assistant` | [home-assistant.json](/install-scripts/home-assistant.json) | 1.6 KB | 2025-12-04 | -| `immich` | [immich.json](/install-scripts/immich.json) | 1.7 KB | 2025-12-04 | -| `jellyfin` | [jellyfin.json](/install-scripts/jellyfin.json) | 2.3 KB | 2025-12-04 | -| `plex` | [plex.json](/install-scripts/plex.json) | 3.4 KB | 2025-12-04 | +| `immich` | [immich.json](/install-scripts/immich.json) | 1.7 KB | 2025-12-12 | +| `jellyfin` | [jellyfin.json](/install-scripts/jellyfin.json) | 2.2 KB | 2025-12-12 | +| `plex` | [plex.json](/install-scripts/plex.json) | 3.4 KB | 2025-12-12 | | `prowlarr` | [prowlarr.json](/install-scripts/prowlarr.json) | 766 B | 2025-12-04 | | `qbittorrent` | [qbittorrent.json](/install-scripts/qbittorrent.json) | 1.0 KB | 2025-12-04 | | `radarr` | [radarr.json](/install-scripts/radarr.json) | 1.2 KB | 2025-12-04 |