You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/features/apps/install-scripts/advanced/debugging.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -27,8 +27,8 @@ If an install scripts fails, this will help:
27
27
28
28
#### Permission Errors
29
29
-**Symptom**: App fails to start, logs show permission denied errors
30
-
-**Solution**: Add appropriate entries to `ensure_permissions_exists` in your install script
31
-
-**Example**: PostgreSQL requires specific user/group permissions
30
+
-**Solution**: Add the `owner` field to the relevant entry in `ensure_directories_exists` with the correct TrueNAS user and group (e.g., `{ "user": "netdata", "group": "docker" }`)
31
+
-**Example**: PostgreSQL data directories typically require `"owner": { "user": "netdata", "group": "docker" }`
32
32
33
33
#### Missing Directories
34
34
-**Symptom**: App fails during installation, "directory not found" errors
Copy file name to clipboardExpand all lines: docs/features/apps/install-scripts/reference/schema.md
+42-19Lines changed: 42 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,15 +4,14 @@ Install scripts are JSON objects with the following structure. Scripts can use v
4
4
5
5
## Root Properties
6
6
7
-
-**`version`** (required): Schema version. Must be `3` or higher (currently latest supported version).
7
+
-**`version`** (required): Schema version. Must be `4` (current required version). Versions 1-3 are deprecated.
8
8
-**`script`** (required): Metadata about the install script itself
9
9
-**`version`** (required): Semantic version of this install script (e.g., "1.0.0", "2.1.3")
10
10
-**`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"`
11
11
-**`changeLog`** (optional): Description of changes in this version of the script
12
12
-**`requirements`** (required): System requirements that are validated before installation
13
13
-**`installation_questions`** (optional): Array of questions to ask the user during installation
14
-
-**`ensure_directories_exists`** (optional): Array of directories to create before installation
15
-
-**`ensure_permissions_exists`** (optional): Array of permission modifications for specific paths
14
+
-**`ensure_directories_exists`** (optional): Array of directory entry objects to create before installation, with optional ownership and snapshot declarations
16
15
-**`app_values`** (required): Configuration object passed directly to TrueNAS API
17
16
18
17
## Available Macros
@@ -83,8 +82,8 @@ Locations are folder paths configured in HexOS Settings → Locations. Each loca
@@ -149,7 +148,7 @@ Network ports that the application will use. HexOS can validate port availabilit
149
148
150
149
```json
151
150
{
152
-
"version": 2,
151
+
"version": 4,
153
152
"requirements": {
154
153
"locations": [
155
154
"ApplicationsPerformance",
@@ -234,19 +233,43 @@ Reference question responses in your `app_values` using the `$QUESTION(key)` syn
234
233
235
234
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.
236
235
237
-
## Directory Creation
238
-
-**String format**: Simple path string
239
-
-**Object format**:
240
-
-`path`: Directory path (required)
241
-
-`network_share`: Boolean, whether to expose as network share
242
-
-`posix`: Boolean, whether to use POSIX permissions
243
-
244
-
## Permission Management
245
-
Required for apps that need specific user/group permissions (like PostgreSQL).
246
-
-`path`: Directory path to modify
247
-
-`username`: User to grant access to
248
-
-`access`: Access level ("read", "write", etc.)
249
-
-`posix`: Object with additional POSIX settings (e.g., `groupname`)
236
+
## Directory Creation, Ownership, and Snapshots
237
+
238
+
Each entry in `ensure_directories_exists` is an object with the following properties:
239
+
240
+
-`path` (required): Directory path, typically using `$LOCATION()` macros
241
+
-`network_share` (optional): Boolean, whether to expose as a network share
242
+
-`owner` (optional): Object specifying the TrueNAS user and group that should own this directory
-`group` (optional): TrueNAS group name (e.g., `"docker"`). If omitted, uses the user's default group
245
+
-`snapshot` (optional): Object with an `id` field. When present, HexOS snapshots this dataset before app updates so support can assist with restoring your application and data if something goes wrong
246
+
-`id` (required): Identifier included in the snapshot name and metadata (e.g., `"db"`, `"config"`)
- HexOS calls `user.get_user_obj` and optionally `group.get_group_obj` on the TrueNAS system to resolve usernames and group names to numeric uid/gid
263
+
- After `app.update` completes, HexOS verifies and repairs ownership on declared paths if TrueNAS changed it
264
+
- If a path has a POSIX1E ACL (legacy), HexOS automatically migrates it to NFS4 with `aclmode: PASSTHROUGH`, snapshots the dataset first as a rollback point, then applies the canonical ACL with the declared uid/gid
265
+
- Only applies to app-specific paths (4+ path segments, e.g., `/mnt/pool/location/app/data`) — location roots are never modified
266
+
- Paths without `owner` are created with default permissions and not tracked for repair
267
+
268
+
**How `snapshot` works:**
269
+
- Before any app update, HexOS snapshots each dataset with a `snapshot` config so support can assist with restoring your application and data if something goes wrong
270
+
- Snapshots are named `hexos-app-{appId}-{id}-{timestamp}` and stamped with metadata: `hexos:purpose`, `hexos:app`, `hexos:snapshot_id`, `hexos:path`
271
+
- Only the latest 3 snapshots per app per dataset are kept — older snapshots are automatically pruned after each new snapshot
272
+
- Only applies to app-specific paths (4+ path segments) — location roots are never snapshotted
250
273
251
274
## App Values
252
275
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).
0 commit comments