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,189 @@
+name: metapluginfullhash
+
+# =============================================================================
+# MetaPlugin · Full Hash — the `full-hash` 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
+# `full-hash` is not one of them. What this app gives you today is the plugin
+# running and addressable at `http://metapluginfullhash-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 `metapluginfullhash-*` prefix + the per-stack `metapluginfullhash`
+# network + /DATA/AppData/metapluginfullhash/ data root, so it installs beside the other Meta* apps with zero
+# collisions.
+# =============================================================================
+
+services:
+  # ---------------------------------------------------------------------------
+  # metapluginfullhash-plugin — the plugin. Listens on 8080; joined to `pcs` so any
+  # consumer on the box can reach it by name. Default queue: background.
+  # ---------------------------------------------------------------------------
+  metapluginfullhash-plugin:
+    image: ghcr.io/worph/metamesh-plugin-fullhash:1.0.0
+    cpu_shares: 30
+    container_name: metapluginfullhash-plugin
+    # 2 GB, swap disabled (memswap_limit == mem_limit) → OOM instead of
+    # swap. Sized for whole-file hashing of large media over WebDAV; this
+    # is the one plugin that genuinely needs it.
+    mem_limit: 2g
+    memswap_limit: 2g
+    hostname: metapluginfullhash-plugin
+    restart: unless-stopped
+    user: "0:0"
+    expose:
+      - 8080
+    environment:
+      # Nothing to configure: this plugin takes its work from the /process
+      # payload and writes back through the caller. No key, no 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/metapluginfullhash/cache:/cache:rw
+    networks:
+      - metapluginfullhash
+      - 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.
+  # ---------------------------------------------------------------------------
+  metapluginfullhash:
+    image: ghcr.io/yundera/appshield:2.0.9
+    cpu_shares: 80
+    container_name: metapluginfullhash
+    hostname: metapluginfullhash
+    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: "metapluginfullhash-plugin"
+      BACKEND_PORT: "8080"
+      LISTEN_PORT: "80"
+    labels:
+      caddy_0: metapluginfullhash-${APP_DOMAIN}
+      caddy_0.import: gateway_tls
+      caddy_0.reverse_proxy: "{{upstreams 80}}"
+      caddy_1: metapluginfullhash-${APP_PUBLIC_IP_DASH}.nip.io
+      caddy_1.import: gateway_tls
+      caddy_1.reverse_proxy: "{{upstreams 80}}"
+      caddy_2: metapluginfullhash-${APP_PUBLIC_IP_DASH}.sslip.io
+      caddy_2.reverse_proxy: "{{upstreams 80}}"
+    depends_on:
+      - metapluginfullhash-plugin
+    networks:
+      - metapluginfullhash
+      - pcs
+
+networks:
+  metapluginfullhash:
+    name: metapluginfullhash
+    driver: bridge
+  pcs:
+    name: ${APP_NET:-pcs}
+    external: true
+
+x-casaos:
+  architectures:
+    - amd64
+    - arm64
+  author: Worph Team
+  category: Developer
+  developer: Aptero Team
+  main: metapluginfullhash
+  webui_port: 80
+  index: /manifest
+
+  description:
+    en_us: |
+      **The `full-hash` enrichment plugin for MetaMesh, as its own app.**
+
+      Hashes a whole file — high-performance parallel hashing with optimised I/O — and writes the SHA-256 CID that duplicate detection keys on.
+
+      ⚠ **The expensive one.** It reads every byte of every file it is given,
+      over WebDAV, on the background queue. The 2 GB limit and the 5-minute
+      timeout are sized for large media files, not padding.
+
+      **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://metapluginfullhash-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 `full-hash`. Installing this
+      gives you the plugin running and addressable on the `pcs` network for
+      anything that speaks the plugin contract; it does **not** add `full-hash` to
+      MetaSort.
+    fr_fr: |
+      **Le plugin d'enrichissement `full-hash` de MetaMesh, en app autonome.**
+
+      Hache un fichier entier — hachage parallèle haute performance — et écrit le CID SHA-256 sur lequel la détection de doublons s'appuie.
+
+      **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://metapluginfullhash-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: Whole-file SHA-256 hashing for MetaMesh (duplicate detection)
+    fr_fr: Hachage SHA-256 de fichiers entiers pour MetaMesh (détection de doublons)
+
+  title:
+    en_us: MetaPlugin · Full Hash
+
+  icon: https://cdn.jsdelivr.net/gh/Worph/MetaAppStore@main/Apps/MetaPluginFullHash/icon.png
+  thumbnail: https://cdn.jsdelivr.net/gh/Worph/MetaAppStore@main/Apps/MetaPluginFullHash/thumbnail.png
+
+  store_app_id: metapluginfullhash
+  is_uncontrolled: false
+
+  tips:
+    before_install:
+      en_us: |
+        ⚠ **Read this first: nothing calls `full-hash` 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 `full-hash` running and
+        addressable at `http://metapluginfullhash-plugin:8080` for your own caller — not
+        expecting it to light up MetaSort or a MetaFeeder on its own.
+
+        **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/metapluginfullhash/cache
+      user: $PUID
+      group: $PGID
+  # Same string as the caddy_0 label, so the tile link and the route agree.
+  webui-host: metapluginfullhash-${domain}
+  webui-path: "/manifest"
@@ -0,0 +1,44 @@
+# MetaPlugin · Full Hash — Rationale
+
+## What deviation / exception is being requested
+
+`metapluginfullhash-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/metapluginfullhash/`, 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/metapluginfullhash/`, which is the unit Maison archives on uninstall.