Skip to content

Latest commit

 

History

History
259 lines (212 loc) · 15.7 KB

plugins.md

File metadata and controls

259 lines (212 loc) · 15.7 KB

Plugins

This page is for the administrator: how to install a plugin or a theme, what you accept when you do, and what the server lets it touch on your host. Everything happens in Admin → Plugins; the pages for plugin authors are listed at the end.

A plugin adds to Evey what it does not do by itself: a section on the home page, an overlay in the player, a metadata source, a theme. Each plugin is a separate process that talks to the server through a local socket, confined by a sandbox and limited to the permissions its manifest declares. Its interface, when it has one, runs in an isolated frame of the page.

![The home page without plugins](images/home-no-plugin.webp){ loading=lazy } Without plugins. ![The home page with the weather plugin](images/home.webp){ loading=lazy } With the example weather plugin: a section at the top, drawn in its own frame.

Install a plugin

  1. In Admin → Plugins, open Install Plugin and choose the Plugin file (.zip). If the author ships a signature, add it in Signature file (.zip.sig, optional). The From URL tab installs from an https:// link instead; a plain http:// link or a path on the server is refused (see Where the package comes from). Append #sha256:<hash> to the link to have the download checked. A repository link, https://github.com/<owner>/<repo>, installs the zip of its latest release, checked against the sha256 the release publishes, and the plugin then follows that repository for its updates (see Automatic updates).
  2. Preview & Install analyses the package without installing it. The preview shows the Permissions and Capabilities the plugin asks for, the result of the Static Analysis and, when a signature was given, the Signature verdict with the publisher. The slots and the hosts are shown at update and on the Security Dashboard.
  3. Read that list as the contract: those are the only things the plugin will be able to do. Confirm, and the plugin starts.
![Admin → Plugins on the demo server](images/admin-plugins.webp){ loading=lazy } Admin → Plugins: the runtimes available, the resource limits, and one card per plugin.

A package whose analysis finds a critical pattern is refused, whatever you answer. Warnings are shown and left to you. The plugin's language must be among the Available Runtimes of the server: the default image ships Python, Node.js, PHP, Ruby and Lua; the -nodejs image keeps Python and Node.js and the -lean image keeps Python only.

!!! tip "Signed plugins" A plugin author can sign the ZIP with cosign; the author's public key travels inside the package. Evey checks the signature on its own (no cosign binary) and tells you Signed by when the key is in your Trusted publishers list, Signed, unknown key with its fingerprint otherwise (one click trusts it), Unsigned or Invalid. An update that changes key, or drops the signature, waits for your explicit acceptance. The policy decides the rest:

```sh
EVEY_PLUGINS_COSIGN_POLICY=enforce   # off | warn | enforce (default)
```

With `enforce`, only trusted publishers install: the Evey project's key is
trusted from the start, and another publisher's key can be trusted from
the install preview. With `warn`, the verdict is shown and nothing is
blocked. Authors: see
[Sign your plugin](plugins/dev-setup.md#7-sign-your-plugin).

Update a plugin

On the plugin's card, Update from source… takes the https:// link of the new ZIP and shows the same preview. An update must carry a higher version than the installed one. When it asks for new permissions, capabilities, slots or hosts, the preview says This update requests new permissions and lists the difference: nothing is applied until you choose Approve and install. The package analysed is the package installed: its hash is checked again when the update is applied. The source can also be the plugin's repository link: the preview is then of its latest release.

Automatic updates

A plugin installed from its repository link, or from one of that repository's release links, follows the repository. The Updates section of its card shows the repository (Change sets another one, or none), the Automatic updates switch, on by default, and what the last look found. Evey looks at the latest release a few minutes after it starts, then every hour; Check now looks at once.

A newer release is judged before anything runs:

What the release holds What happens
Nothing new: no new permission, capability, slot or host, no new kind of analysis warning, the same signing key Installed on its own: Version … installed automatically.
Something new (a permission, a host, a change between theme and plugin, another language), a pre-release, an installed version that is not signed, or the switch off Version … awaits your approval, and the admins get a notification. Review opens the usual update preview, where you approve the difference.
Code the static analysis refuses Version … refused, with the reason, and the admins get a notification. It is not installed, automatically or by hand.

An unsigned plugin never updates on its own: whoever took over its repository could publish code the analysis does not catch, and only a signing key they do not hold stops them. A notification is sent once per release, not every hour. The check reads the GitHub API and downloads from the repository's release files, and from nowhere else.

The repository is followed by the permanent number GitHub gives it, not by its name: a renamed or transferred repository is still followed, and whoever registers an abandoned name gets nothing followed. Installing from the repository link installs the release the preview showed, even if a newer one is published in between. A release already judged is not downloaded again until something changes on either side. Evey asks GitHub without a token, which allows 60 requests an hour per address: one per followed plugin and per hour; when the quota is spent, the check stops until its next run.

Manage the installed plugins

Each card shows the plugin's state (Enabled or Disabled) and offers:

Action What it does
Enabled / Disabled Starts or stops the plugin's process. A disabled plugin keeps its files and its configuration.
Config The settings the plugin declares (an API key, a city, a unit...). Secret fields are shown masked and are never sent back to the browser.
Logs The last lines the plugin wrote through the host.
Metadata On a metadata plugin only: the fields it replaces and the fetch of the existing library (below).
Uninstall Removes the process, the files and the plugin's stored data.

Resource limits, at the top of the page, caps every plugin process. The values in the panel are the defaults; the environment variable sets them when the panel has never been saved.

Field Default Environment variable
Max memory (MiB) 256 EVEY_PLUGINS_MEMORY_MB
Max processes 64 EVEY_PLUGINS_PIDS_MAX
Max disk (MiB) 100 EVEY_PLUGINS_DISK_MAX_MB
CPU nice (0-19) 10 EVEY_PLUGINS_CPU_NICE
Sandbox mode auto EVEY_PLUGINS_SANDBOX_MODE

Memory, processes and disk apply at the next sweep of the monitor, which stops a plugin that exceeds them; the CPU priority applies to plugins started afterwards, and a sandbox-mode change restarts the running plugins at once. 0 restores the default for memory and processes; only the disk limit treats 0 as off.

The Security Dashboard keeps, per plugin, the findings of the analysis, the signature result and the last error. Its Host sandbox line shows the sandbox mode actually in force on this machine: if it reads basic, the host offers no per-path filesystem isolation, and Plugin sandbox setup explains what to change.

Plugins are enabled by default. EVEY_PLUGINS_ENABLED=false turns the whole subsystem off.

Metadata plugins

A metadata plugin (capability metadata.provider) gives its own text for your movies and series, from a source other than TMDB. It does not replace TMDB: TMDB still identifies each title and gives its cast, its artwork, its ratings, its collections and its translations. The plugin's text is kept beside TMDB's, and shown in its place field by field.

What a viewer reads, from the weakest to the strongest:

  1. TMDB's text, in the viewer's language when TMDB has it;
  2. the plugin's text in that language, for the fields the plugin is allowed to replace;
  3. your own edit of the title (Edit metadata on its page), which always wins.

Metadata on the plugin's card chooses the fields it replaces among Title, Overview and Tagline. Until you choose, a plugin replaces the overview and the tagline, never the title. A change applies at once to what the plugin already gave; nothing is fetched again.

The plugin is asked about every movie and series as it is matched or refreshed. Fetch for the whole library, on the same panel, asks it about the titles already there, one after the other, and shows how far it has gone and, at the end, how many it found and how many got no answer. A refresh of the title from TMDB never overwrites the plugin's text; disabling the plugin hides that text, uninstalling it deletes it.

Seasons and episodes keep TMDB's text, and search still matches TMDB's titles.

What a plugin can do on your host

Whatever its manifest says, a plugin:

  • sees its own directory, not the server's data nor the media files;
  • has no direct network access: a plugin with the network permission reaches only the hosts it declared, through the server, with GET and HEAD;
  • cannot start child processes unless it declares subprocess;
  • runs under the resource limits above and, when the host allows it, under a separate user.

Its interface is confined to the slots the manifest declares: a section or the hero area of the home page, a sidebar panel in a library or on a detail page, an overlay of the player, the appearance settings, the bottom of the navigation sidebar, or one entry in the admin menu that opens the plugin's own page. A plugin can never draw into the sign-in, setup, security or existing admin screens. In its frame, it has no access to the page, your cookies or your session: what it reads from the server goes through a short-lived token limited to the two permissions it may ask for (public for a safe projection of media titles and posters, prefs for the current user's preferences in its own namespace).

The permissions a plugin can ask for are listed in Permissions and slots. How the sandbox works, and what it still cannot prevent, is in Plugin sandbox and threat model.

!!! warning "The server checks where a plugin talks, not what it says" Once a host is on a plugin's list, the server cannot inspect what the plugin sends to it. Review a third-party plugin before installing it, as you would any software, and treat its host list as the list of parties that may receive your library's titles.

Themes

A theme is a package of kind: theme with no process: a stylesheet, and optionally a script confined to a hidden frame. It is installed from the same Install Plugin dialog; the stylesheet is sanitized at install. Each user then picks it under Settings → Appearance → Theme. What a theme may contain is described in Themes.

Writing a plugin

Page Contents
Writing a plugin A first plugin step by step, the install loop, signing, distribution. Start here.
Plugin API reference The manifest, the backend calls and data store, the evey.* bridge of the interface.
Permissions and slots What a manifest may declare, what is checked at install, the external fetch rules, the slots.
Themes Restyling the interface with CSS and a sandboxed script.
Webhooks and API keys Integrating Evey with other tools without writing a plugin.