add app for each plugin

2026-09-13 19:47:17 +02:00
parent 39f82e1f96
commit cb067ee50f
84 changed files with 7072 additions and 3 deletions
@@ -0,0 +1,194 @@
+name: metapluginffmpeg
+
+# =============================================================================
+# MetaPlugin · FFmpeg — the `ffmpeg` enrichment plugin, as a standalone app.
+#
+# A MetaMesh enrichment plugin is a HEADLESS worker: it speaks the four-verb
+# plugin HTTP contract (`/manifest`, `/health`, `/configure`, `/process`) and
+# nothing else. There is no dashboard — the web UI on this tile is the plugin's
+# own `/manifest`, which is how you confirm it is alive and what version it is.
+#
+# ⚠ NOTHING IN THE FAMILY CONSUMES IT BY URL YET — install it knowing that.
+# MetaSort starts its own plugin containers from `plugins.yml` (`image:`) and
+# has no URL slot. The feeder SDK has exactly three sidecar slots
+# (`FILENAME_PARSER_URL`, `TMDB_PLUGIN_URL`, `OPENSUBTITLES_PLUGIN_URL`) and
+# `ffmpeg` is not one of them. What this app gives you today is the plugin
+# running and addressable at `http://metapluginffmpeg-plugin:8080` for anything that
+# speaks the four-verb plugin contract — your own caller, a probe, a future
+# consumer. It is packaging ahead of the consumer, on purpose.
+#
+# ⚠ IT HOLDS NO CREDENTIALS. The caller POSTs `/configure` with its own key
+# (TMDB token, OpenSubtitles account) before use. Two consumers sharing one
+# instance are last-writer-wins on that config — same key, no problem; different
+# keys, install a second copy.
+#
+# Everything is scoped under the `metapluginffmpeg-*` prefix + the per-stack `metapluginffmpeg`
+# network + /DATA/AppData/metapluginffmpeg/ data root, so it installs beside the other Meta* apps with zero
+# collisions.
+# =============================================================================
+
+services:
+  # ---------------------------------------------------------------------------
+  # metapluginffmpeg-plugin — the plugin. Listens on 8080; joined to `pcs` so any
+  # consumer on the box can reach it by name. Default queue: fast.
+  # ---------------------------------------------------------------------------
+  metapluginffmpeg-plugin:
+    image: ghcr.io/worph/metamesh-plugin-ffmpeg:1.0.0
+    cpu_shares: 30
+    container_name: metapluginffmpeg-plugin
+    # Hard RAM cap, swap disabled (memswap_limit == mem_limit) → OOM
+    # instead of swap. Mirrors the limits the bundled sidecars run with.
+    mem_limit: 512m
+    memswap_limit: 512m
+    hostname: metapluginffmpeg-plugin
+    restart: unless-stopped
+    user: "0:0"
+    expose:
+      - 8080
+    environment:
+      # Where the plugin writes the artefacts it produces (posters, stills,
+      # extracted subtitles) — the shared MetaCore's WebDAV over `pcs`.
+      # LOAD-BEARING: the published images resolve WebDAV from this var, and
+      # without it they log "WebDAV client unavailable" and silently write
+      # nothing. Every record then fails MetaWatch's poster gate.
+      WEBDAV_URL: "http://metacore-app:9000/webdav"
+      TZ: "$TZ"
+    volumes:
+      # Plugin cache. Persisted so a recreate does not redo work that is
+      # expensive to redo; safe to delete, it rebuilds.
+      - ${DATA_ROOT:-/DATA}/AppData/metapluginffmpeg/cache:/cache:rw
+    networks:
+      - metapluginffmpeg
+      - pcs
+
+  # ---------------------------------------------------------------------------
+  # AppShield gate — the plugin's `/manifest` behind Yundera OIDC SSO.
+  # container_name == subdomain prefix (the auth-registrar derives the client_id
+  # from it). Consumers still reach the plugin directly on `pcs`; this gate
+  # exists so `/process` and `/configure` are never reachable from the internet
+  # without a session.
+  # ---------------------------------------------------------------------------
+  metapluginffmpeg:
+    image: ghcr.io/yundera/appshield:2.0.9
+    cpu_shares: 80
+    container_name: metapluginffmpeg
+    hostname: metapluginffmpeg
+    restart: unless-stopped
+    user: "0:0"
+    expose:
+      - 80
+    environment:
+      OIDC_REGISTRAR_URL: "http://auth-registrar:9092"
+      REDIRECT_HOST_SUFFIXES: "${APP_DOMAIN},${APP_PUBLIC_IP_DASH}.nip.io,${APP_PUBLIC_IP_DASH}.sslip.io"
+      BACKEND_HOST: "metapluginffmpeg-plugin"
+      BACKEND_PORT: "8080"
+      LISTEN_PORT: "80"
+    labels:
+      caddy_0: metapluginffmpeg-${APP_DOMAIN}
+      caddy_0.import: gateway_tls
+      caddy_0.reverse_proxy: "{{upstreams 80}}"
+      caddy_1: metapluginffmpeg-${APP_PUBLIC_IP_DASH}.nip.io
+      caddy_1.import: gateway_tls
+      caddy_1.reverse_proxy: "{{upstreams 80}}"
+      caddy_2: metapluginffmpeg-${APP_PUBLIC_IP_DASH}.sslip.io
+      caddy_2.reverse_proxy: "{{upstreams 80}}"
+    depends_on:
+      - metapluginffmpeg-plugin
+    networks:
+      - metapluginffmpeg
+      - pcs
+
+networks:
+  metapluginffmpeg:
+    name: metapluginffmpeg
+    driver: bridge
+  pcs:
+    name: ${APP_NET:-pcs}
+    external: true
+
+x-casaos:
+  architectures:
+    - amd64
+    - arm64
+  author: Worph Team
+  category: Developer
+  developer: Aptero Team
+  main: metapluginffmpeg
+  webui_port: 80
+  index: /manifest
+
+  description:
+    en_us: |
+      **The `ffmpeg` enrichment plugin for MetaMesh, as its own app.**
+
+      Probes video, audio and subtitle streams with FFprobe and writes the `stream/*` keys — codec, resolution, duration, per-track language.
+
+      Its probe is the *authoritative* source for anything a filename can only
+      guess at — `real-probe > title-guess`.
+
+      **Headless.** It answers the plugin HTTP contract — `/manifest`, `/health`,
+      `/configure`, `/process` — and has no dashboard; this tile opens its
+      `/manifest`. Point a consumer at `http://metapluginffmpeg-plugin:8080`.
+
+      ⚠ **No MetaMesh app calls it by URL yet.** MetaSort starts its own plugin
+      containers from `plugins.yml`, and the MetaFeeder SDK's sidecar slots cover
+      only filename-parser, TMDB and OpenSubtitles — not `ffmpeg`. Installing this
+      gives you the plugin running and addressable on the `pcs` network for
+      anything that speaks the plugin contract; it does **not** add `ffmpeg` to
+      MetaSort.
+    fr_fr: |
+      **Le plugin d'enrichissement `ffmpeg` de MetaMesh, en app autonome.**
+
+      Sonde les flux vidéo, audio et sous-titres avec FFprobe et écrit les clés `stream/*` — codec, résolution, durée, langue par piste.
+
+      **Sans interface.** Il répond au contrat HTTP des plugins — `/manifest`,
+      `/health`, `/configure`, `/process` — et n'a pas de tableau de bord ; cette
+      tuile ouvre son `/manifest`. Dirigez un consommateur vers
+      `http://metapluginffmpeg-plugin:8080`.
+
+      **Ce n'est pas un plugin MetaSort** : MetaSort démarre ses propres
+      conteneurs de plugins depuis `plugins.yml` et n'accepte pas d'URL.
+  tagline:
+    en_us: FFprobe stream metadata for MetaMesh records
+    fr_fr: Métadonnées de flux FFprobe pour les enregistrements MetaMesh
+
+  title:
+    en_us: MetaPlugin · FFmpeg
+
+  icon: https://cdn.jsdelivr.net/gh/Worph/MetaAppStore@main/Apps/MetaPluginFFmpeg/icon.png
+  thumbnail: https://cdn.jsdelivr.net/gh/Worph/MetaAppStore@main/Apps/MetaPluginFFmpeg/thumbnail.png
+
+  store_app_id: metapluginffmpeg
+  is_uncontrolled: false
+
+  tips:
+    before_install:
+      en_us: |
+        ⚠ **Read this first: nothing calls `ffmpeg` by URL yet.** MetaSort spawns
+        its own plugin containers from `plugins.yml` (`image:`) and has no URL
+        slot, and the MetaFeeder SDK's three sidecar slots are filename-parser,
+        TMDB and OpenSubtitles only. Install this if you want `ffmpeg` running and
+        addressable at `http://metapluginffmpeg-plugin:8080` for your own caller — not
+        expecting it to light up MetaSort or a MetaFeeder on its own.
+
+        **Requires MetaCore** on the same box: this plugin writes what it
+        produces to MetaCore's WebDAV (`http://metacore-app:9000/webdav`).
+
+        **Authentication:** the `/manifest` page is protected by Yundera's Authelia
+        (OIDC). Consumers on the `pcs` network bypass the gate by design.
+
+# Maison (Yundera dashboard) configuration. Read in preference to x-casaos.
+# schema_version 2 is required for `folders`: an older Maison refuses the app
+# outright rather than starting it without its directories.
+x-compose-app:
+  schema_version: 2
+  # Created and chowned by Maison before any image is pulled, before any hook
+  # runs and before the containers start — on the first boot and every one after.
+  # Compose would otherwise create a missing bind source as a root-owned dir.
+  folders:
+    - path: /DATA/AppData/metapluginffmpeg/cache
+      user: $PUID
+      group: $PGID
+  # Same string as the caddy_0 label, so the tile link and the route agree.
+  webui-host: metapluginffmpeg-${domain}
+  webui-path: "/manifest"
@@ -0,0 +1,44 @@
+# MetaPlugin · FFmpeg — Rationale
+
+## What deviation / exception is being requested
+
+`metapluginffmpeg-plugin` runs `user: 0:0`.
+
+## Why it is necessary
+
+The `metamesh-plugin-*` images declare no `USER` and have always run as root, both
+when MetaSort spawns them and when a MetaFeeder bundles them as an enrichment
+sidecar. This listing is a packaging change — the same image, started by Maison
+instead of by MetaSort — so it keeps the runtime user the image was built and
+validated with.
+
+## Security mitigations in place
+
+- Public ingress terminates at the AppShield sidecar (`ghcr.io/yundera/appshield:2.0.9`),
+  which gates every path behind the PCS's Authelia SSO over OIDC. The plugin carries no
+  Caddy labels and publishes no host port, so `/process` and `/configure` are reachable
+  only from the `pcs` Docker network.
+- The container mounts **no user directories** — not `/DATA/Documents`, `/DATA/Downloads`,
+  `/DATA/Media` or `/DATA/Gallery`.
+  Its only bind is its own cache under `/DATA/AppData/metapluginffmpeg/`, declared in
+  `x-compose-app.folders` and owned `$PUID:$PGID`. It reads the files it works on over
+  MetaCore's WebDAV, never from a bind mount.
+- It holds **no credentials of its own**: keys arrive per-caller over `/configure` and
+  are never written to this app's storage.
+- `cpu_shares` and a hard `mem_limit` (swap disabled) set on every service; image tags
+  pinned; no `:latest`.
+
+## Alternatives considered and rejected
+
+- **Run as `$PUID:$PGID`.** Not validated for these images; a uid change belongs in the
+  plugin image, not in a store listing that is otherwise a pure repackaging.
+- **No AppShield gate, no public route at all.** Rejected: the tile would have no way to
+  show whether the plugin is alive, and `/manifest` is the only status surface a headless
+  plugin has.
+- **Expose it unauthenticated.** Rejected outright — `/process` takes URLs and does work
+  on request, and `/configure` accepts credentials.
+
+## Data protection
+
+The plugin holds no user media and no user account. Its only state is a rebuildable cache under
+`/DATA/AppData/metapluginffmpeg/`, which is the unit Maison archives on uninstall.