OliveTin/docs/modules/ROOT/pages/entities/intro.adoc

[#entities]
= Entities

An entity is something that exists - a "thing", like a VM, or a Container is an entity. OliveTin allows you to then dynamically generate actions based around these entities.

This is really useful if you want to generate wake on lan or poweroff actions for `server` entities, for example.

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 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.
* **Entity file path changes** — when you change an entity's file path in config and reload, OliveTin switches to the new file without a restart.
* **Removing or renaming entity types** — restart OliveTin if you remove an entity definition or rename its type; otherwise stale entity data may remain in memory until restart.

[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 }}`.

Entity field values are **not** sanitized for shell safety. If you substitute them into `shell` or `shellAfterCompleted`, OliveTin assumes the entity files are server-controlled and that you accept responsibility for that data. See xref:action_execution/shellvsexec.adoc#shell-entity-env-trust[Entity and .Env values are not shell-sanitized].

To control which fields appear in the Entities page table and entity details view, configure `properties` on the entity definition in `config.yaml`. See xref:entities/properties.adoc[Entity properties] for details.

To restrict which users may see an entity type (list, details, search, and related UI), list `acls` on the entity definition. See xref:security/acl.adoc#acls[Access Control Lists] (Entities section). Entity types with no `acls` stay unrestricted.

[source,yaml]
----
entities:
  - file: /etc/OliveTin/containers.json
    name: container

  - file: /etc/OliveTin/servers.yaml
    name: server
    icon: ssh
    acls:
      - ops
    properties:
      - name: hostname
        title: Hostname
      - name: ip
        title: IP
----

Entity Actions can only be used on xref:dashboards/intro.adoc[Dashboards].

== What's Next?

Now that you understand entities, here's how to use them effectively:

* xref:entities/properties.adoc[Configure entity properties] - Choose which fields appear in the UI and API
* xref:entities/icons.adoc[Configure entity icons] - Set an icon for each entity type
* xref:entities/yaml.adoc[Create YAML entity files] - Learn the YAML format for entity files
* xref:entities/json.adoc[Create JSON entity files] - Learn the JSON format for entity files
* xref:entities/examples.adoc[View entity examples] - See complete examples of entity configurations
* xref:dashboards/intro.adoc[Use entities in dashboards] - Combine entities with dashboards for dynamic action generation
* xref:solutions/container-control-panel/index.adoc[Container control panel solution] - See a complete example using container entities
* xref:solutions/systemd-control-panel/index.adoc[Systemd control panel solution] - See a complete example using systemd entities