From 94c497988cc6b6e59bd60d87fd82247e3209127e Mon Sep 17 00:00:00 2001 From: jamesread Date: Thu, 10 Sep 2026 09:33:03 +0100 Subject: [PATCH 1/2] docs: entity display names, live reload, and Docker watch limits Document which fields become entity instance names, clarify JSON vs docker field names, describe live reload behaviour for entity files and new config entries, and note Docker Desktop file-watch limitations. Part of #996 Co-authored-by: Cursor --- docs/modules/ROOT/pages/config.adoc | 2 +- docs/modules/ROOT/pages/entities/intro.adoc | 25 ++++++++++++++++++- docs/modules/ROOT/pages/entities/json.adoc | 16 ++++++++++-- .../ROOT/pages/entities/properties.adoc | 2 +- docs/modules/ROOT/pages/entities/yaml.adoc | 5 ++-- 5 files changed, 43 insertions(+), 7 deletions(-) diff --git a/docs/modules/ROOT/pages/config.adoc b/docs/modules/ROOT/pages/config.adoc index 663fcfbb..9307c624 100644 --- a/docs/modules/ROOT/pages/config.adoc +++ b/docs/modules/ROOT/pages/config.adoc @@ -37,7 +37,7 @@ All configuration options are covered in the solution sections | Option | Description | Default | Live Reloadable | Documentation | `actions` | The list of available actions. | `-` | Live Reloadable, but refreshing the web browser is recommended. | xref:action_examples/intro.adoc[Action examples] -| `entities` | A list of "things" you can attach actions to. | `-` | Live Reloadable, but restart is recommended. | xref:entities/intro.adoc[Entities] +| `entities` | A list of "things" you can attach actions to. | `-` | Entity data files reload live; new entity definitions in config reload live. Restart if removing types or changing file paths. | xref:entities/intro.adoc[Entities] | `dashboards` | A grouping of actions, with optional displays, or actions generated from entities. | `-` | Live Reloadable | xref:dashboards/intro.adoc[Dashboards] |=== diff --git a/docs/modules/ROOT/pages/entities/intro.adoc b/docs/modules/ROOT/pages/entities/intro.adoc index ef4864b5..9afe9acf 100644 --- a/docs/modules/ROOT/pages/entities/intro.adoc +++ b/docs/modules/ROOT/pages/entities/intro.adoc @@ -7,7 +7,30 @@ This is really useful if you want to generate wake on lan or poweroff actions fo A very popular use case that entities were designed for was for `container` entities - in a similar way you could generate `start`, `stop`, and `restart` container actions. -Entities are just loaded from files on disk, OliveTin will also watch these files for updates while OliveTin is running, and update entities. +Entities are just loaded from files on disk. OliveTin watches these files for updates while it is running and refreshes dashboards, actions, and the Entities page when data changes. + +[#display-names] +=== Display names + +Each entity instance needs a human-readable name in the UI. OliveTin picks the first matching string field from this list (case-insensitive field names): + +`title`, `name`, `id`, `hostname`, `host`, `label` + +If none of those fields contain a string value, the instance appears as **Untitled Entity**. Add one of those fields to every row in your entity file — for example `title: My Vehicle` or `name: server1`. + +The chosen field is shown as the instance name in lists and dashboards. It is not repeated again in the entity details field list. + +[#entity-live-reload] +=== Live reload + +* **Entity file content** — when a watched data file is updated on disk, OliveTin reloads instances and notifies the web UI. No restart is required. +* **New entity types in `config.yaml`** — when you add a new entry under `entities:` and reload config, OliveTin starts watching that file without a full restart (from OliveTin 3k builds including the #996 live-reload fix). +* **Removing or renaming entity types** — restart OliveTin if you remove an entity definition or change its file path. + +[NOTE] +==== +On **Docker Desktop for Windows**, bind-mounted entity files may not trigger file-watch events when updated from the host (for example by a cron job writing through a volume). If live reload does not pick up changes, restart the container after updating the file, run OliveTin on Linux, or write the file in place on the same filesystem OliveTin watches. +==== Entity data files can contain any fields you need. Those values are available in action templates as `{{ .CurrentEntity.field }}` — for example, `{{ .CurrentEntity.status }}` or `{{ .CurrentEntity.hostname }}`. diff --git a/docs/modules/ROOT/pages/entities/json.adoc b/docs/modules/ROOT/pages/entities/json.adoc index 490967fb..ffae045b 100644 --- a/docs/modules/ROOT/pages/entities/json.adoc +++ b/docs/modules/ROOT/pages/entities/json.adoc @@ -3,10 +3,22 @@ JSON files are parsed as if each line is a single JSON object. This can be super helpful for getting a list of containers, for example; `docker ps -a --format=json > /etc/OliveTin/containers.json`. +== Display names in JSON + +OliveTin uses the first string value found in fields named `title`, `name`, `id`, `hostname`, `host`, or `label` as the instance name in the UI. See xref:entities/intro.adoc#display-names[Display names] in the entities overview. + +Docker's JSON output uses `Names`, which is **not** one of those fields. Either map it when generating the file (for example with `jq` to add a `name` field) or include an explicit `title` or `name` key in each object. + [source,json] -.`/etc/OliveTin/containers.json` +.Example with an explicit display name +---- +{"title":"media-indexing-container","ID":"4bafe6f9f956","Image":"fedora","State":"exited"} +{"title":"media-playback-container","ID":"d25f37c49c35","Image":"fedora","State":"exited"} +---- + +[source,json] +.Raw `docker ps --format=json` lines (add `title` or `name` for OliveTin display names) ---- {"Command":"\"/opt/entrypoint.sh\"","CreatedAt":"2024-02-08 15:27:42 +0000 GMT","ID":"4bafe6f9f956","Image":"fedora","Labels":"?","LocalVolumes":"0","Mounts":"","Names":"media-indexing-container","Networks":"bridge","Ports":"","RunningFor":"13 days ago","Size":"0B","State":"exited","Status":"Exited (128) 13 days ago"} {"Command":"\"/opt/entrypoint.sh\"","CreatedAt":"2023-12-17 20:58:03 +0000 GMT","ID":"d25f37c49c35","Image":"fedora","Labels":"?","LocalVolumes":"0","Mounts":"","Names":"media-playback-container","Networks":"bridge","Ports":"","RunningFor":"27 days ago","Size":"0B","State":"exited","Status":"Exited (137) 27 days ago"} ---- - diff --git a/docs/modules/ROOT/pages/entities/properties.adoc b/docs/modules/ROOT/pages/entities/properties.adoc index 4f89c4d8..3f914b76 100644 --- a/docs/modules/ROOT/pages/entities/properties.adoc +++ b/docs/modules/ROOT/pages/entities/properties.adoc @@ -63,7 +63,7 @@ When `properties` is omitted or empty, the Entities page shows a simple list of === Entity details page -The entity details view shows only the fields listed in `properties`, plus type and title. +The entity details view shows only the fields listed in `properties`, plus type. The instance name appears in the page title, not again in the field list. If `properties` is not configured, all top-level fields from the entity data file are shown. diff --git a/docs/modules/ROOT/pages/entities/yaml.adoc b/docs/modules/ROOT/pages/entities/yaml.adoc index 897b762c..37779ce0 100644 --- a/docs/modules/ROOT/pages/entities/yaml.adoc +++ b/docs/modules/ROOT/pages/entities/yaml.adoc @@ -1,7 +1,9 @@ [#entities-yaml] = YAML entity files -YAML files are the default expected format, so you can use .yml, .yaml, or even .txt - as long as the file contains a valid yaml LIST, then it will be loaded. +YAML files are the default expected format, so you can use .yml, .yaml, or even .txt - as long as the file contains a valid yaml LIST, then it will be loaded. + +Each list item should include a display name field (`title`, `name`, `id`, `hostname`, `host`, or `label`). The example below uses `name`. See xref:entities/intro.adoc#display-names[Display names]. .`/etc/OliveTin/servers.yaml` [source,yaml] @@ -19,4 +21,3 @@ YAML files are the default expected format, so you can use .yml, .yaml, or even hostname: server3.example.com ip: 192.168.0.3 ---- - From 961eaf6e3c522a586234dd2f22f792222fcaa263 Mon Sep 17 00:00:00 2001 From: jamesread Date: Thu, 10 Sep 2026 09:49:55 +0100 Subject: [PATCH 2/2] docs: address CodeRabbit review on entity display-name docs Remove the unconditional field-list exclusion claim, drop the incorrect #996 release reference, document Docker ID fallback for JSON entities, and add an explicit entity-details-page anchor for cross-references. Co-authored-by: Cursor --- docs/modules/ROOT/pages/entities/intro.adoc | 4 ++-- docs/modules/ROOT/pages/entities/json.adoc | 6 +++--- docs/modules/ROOT/pages/entities/properties.adoc | 1 + 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/modules/ROOT/pages/entities/intro.adoc b/docs/modules/ROOT/pages/entities/intro.adoc index 9afe9acf..6393c931 100644 --- a/docs/modules/ROOT/pages/entities/intro.adoc +++ b/docs/modules/ROOT/pages/entities/intro.adoc @@ -18,13 +18,13 @@ Each entity instance needs a human-readable name in the UI. OliveTin picks the f If none of those fields contain a string value, the instance appears as **Untitled Entity**. Add one of those fields to every row in your entity file — for example `title: My Vehicle` or `name: server1`. -The chosen field is shown as the instance name in lists and dashboards. It is not repeated again in the entity details field list. +The chosen field is shown as the instance name in lists and dashboards. On the entity details page, it appears in the page heading; see xref:entities/properties.adoc#entity-details-page[Entity details page] for which other fields are listed. [#entity-live-reload] === Live reload * **Entity file content** — when a watched data file is updated on disk, OliveTin reloads instances and notifies the web UI. No restart is required. -* **New entity types in `config.yaml`** — when you add a new entry under `entities:` and reload config, OliveTin starts watching that file without a full restart (from OliveTin 3k builds including the #996 live-reload fix). +* **New entity types in `config.yaml`** — when you add a new entry under `entities:` and reload config, OliveTin starts watching that file without a full restart. * **Removing or renaming entity types** — restart OliveTin if you remove an entity definition or change its file path. [NOTE] diff --git a/docs/modules/ROOT/pages/entities/json.adoc b/docs/modules/ROOT/pages/entities/json.adoc index ffae045b..e332bb8d 100644 --- a/docs/modules/ROOT/pages/entities/json.adoc +++ b/docs/modules/ROOT/pages/entities/json.adoc @@ -5,9 +5,9 @@ JSON files are parsed as if each line is a single JSON object. This can be super == Display names in JSON -OliveTin uses the first string value found in fields named `title`, `name`, `id`, `hostname`, `host`, or `label` as the instance name in the UI. See xref:entities/intro.adoc#display-names[Display names] in the entities overview. +OliveTin uses the first string value found in fields named `title`, `name`, `id`, `hostname`, `host`, or `label` as the instance name in the UI. Matching is case-insensitive. See xref:entities/intro.adoc#display-names[Display names] in the entities overview. -Docker's JSON output uses `Names`, which is **not** one of those fields. Either map it when generating the file (for example with `jq` to add a `name` field) or include an explicit `title` or `name` key in each object. +Docker's JSON output uses `Names`, which is **not** one of those fields. Without `title` or `name`, OliveTin falls back to Docker's `ID` field (matched as `id`) and shows the container ID instead of the human-readable name. Either map `Names` when generating the file (for example with `jq` to add a `name` field) or include an explicit `title` or `name` key in each object. [source,json] .Example with an explicit display name @@ -17,7 +17,7 @@ Docker's JSON output uses `Names`, which is **not** one of those fields. Either ---- [source,json] -.Raw `docker ps --format=json` lines (add `title` or `name` for OliveTin display names) +.Raw `docker ps --format=json` lines (without `title` or `name`, OliveTin shows `ID` instead of `Names`) ---- {"Command":"\"/opt/entrypoint.sh\"","CreatedAt":"2024-02-08 15:27:42 +0000 GMT","ID":"4bafe6f9f956","Image":"fedora","Labels":"?","LocalVolumes":"0","Mounts":"","Names":"media-indexing-container","Networks":"bridge","Ports":"","RunningFor":"13 days ago","Size":"0B","State":"exited","Status":"Exited (128) 13 days ago"} {"Command":"\"/opt/entrypoint.sh\"","CreatedAt":"2023-12-17 20:58:03 +0000 GMT","ID":"d25f37c49c35","Image":"fedora","Labels":"?","LocalVolumes":"0","Mounts":"","Names":"media-playback-container","Networks":"bridge","Ports":"","RunningFor":"27 days ago","Size":"0B","State":"exited","Status":"Exited (137) 27 days ago"} diff --git a/docs/modules/ROOT/pages/entities/properties.adoc b/docs/modules/ROOT/pages/entities/properties.adoc index 3f914b76..243ede85 100644 --- a/docs/modules/ROOT/pages/entities/properties.adoc +++ b/docs/modules/ROOT/pages/entities/properties.adoc @@ -61,6 +61,7 @@ When `properties` is configured, the Entities page shows a searchable, paginated When `properties` is omitted or empty, the Entities page shows a simple list of instance names and a total count instead of a table. +[#entity-details-page] === Entity details page The entity details view shows only the fields listed in `properties`, plus type. The instance name appears in the page title, not again in the field list.