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..6393c931 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. 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. +* **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..e332bb8d 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. 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. 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] -.`/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 (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 4f89c4d8..243ede85 100644 --- a/docs/modules/ROOT/pages/entities/properties.adoc +++ b/docs/modules/ROOT/pages/entities/properties.adoc @@ -61,9 +61,10 @@ 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 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 ---- -