MetaAppStore/Apps/MetaSort

MetaSort - MetaMesh Ecosystem

MetaSort is part of the MetaMesh ecosystem, a suite of 4 interconnected apps that work together to organize and serve your media library.

The MetaMesh Ecosystem

App	Role	Port	Dependency
MetaCore	Leader election, Redis, WebDAV, Authelia SSO	80, 9091	None (install first)
MetaSort	Metadata extraction, file indexing, plugin system	80	Requires MetaCore
MetaFuse	Virtual filesystem (FUSE + WebDAV)	80	Requires MetaCore
MetaStremio	Stremio addon with HLS transcoding	7000	Requires MetaCore

┌─────────────────────────────────────────────────────────────┐
│                     User's Media Files                       │
│              /DATA/Downloads, /DATA/Media                    │
└──────────────────────────┬──────────────────────────────────┘
                           │ (read-only bind mounts at /files/watch/*)
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                       MetaCore                               │
│  • Leader election (flock)                                   │
│  • Redis (metadata storage)                                  │
│  • Authelia OIDC (single sign-on for all dashboards)         │
│  • WebDAV file serving + dynamic mount management            │
└──────────────────────────┬──────────────────────────────────┘
                           │
           ┌───────────────┼───────────────┐
           ▼               ▼               ▼
      /DATA/AppData/metacore/meta-core    pcs (Yundera platform network)
      (bind mount)              (inter-container comms)
           │                           │
     ┌─────┴─────┐  ┌─────────────┐  ┌─────────────┐
     ▼           ▼  ▼             ▼  ▼             ▼
┌─────────┐ ┌─────────┐  ┌─────────────┐
│MetaSort │ │MetaFuse │  │ MetaStremio │
└─────────┘ └─────────┘  └─────────────┘

Shared Infrastructure

MetaCore Directory (/DATA/AppData/metacore/meta-core)

A bind mount shared by all MetaMesh apps. Contains:

/DATA/AppData/metacore/meta-core/
├── db/redis/          # Redis database (metadata storage)
├── locks/             # Leader election lock files (kv-leader.info)
└── services/          # Service discovery JSON files

Why a bind mount?

• Persists independently of Docker volume lifecycle
• Predictable location for debugging/backup
• Survives app reinstalls

User media directories — only mounted into MetaCore

User media is bind-mounted only into the MetaCore container:

/files/                       (inside MetaCore container)
└── watch/
    ├── downloads/            # ← /DATA/Downloads (host bind, read-only)
    └── media/                # ← /DATA/Media     (host bind, read-only)

MetaSort, MetaFuse, and MetaStremio do not mount /files at all. They reach files through MetaCore's WebDAV endpoint (http://metacore/webdav/*), discovering the URL at runtime from the leader-info file in /meta-core/locks/kv-leader.info.

This matches the dev stack (Architecture V3) — MetaCore is the single source of truth for media files; siblings are stateless w.r.t. file storage.

Earlier versions had two problems here:

1. A metamesh-files named volume mounted at /files with the user's media bind-mounted as subpaths. docker volume rm metamesh-files then recursively traversed the bind-mount targets (which shared inodes with the host paths) and deleted everything in /DATA/Downloads and /DATA/Media.
2. Even after dropping the named volume, every sibling app duplicated the bind mounts of /DATA/Downloads and /DATA/Media — multiplying the blast radius of any future bind-mount footgun and breaking the "MetaCore owns files" architectural promise.

Mounting media only into MetaCore eliminates both issues.

Network (pcs)

All MetaMesh containers attach to the Yundera platform network pcs (declared external: true everywhere). No app-private docker network — services discover each other by container hostname over pcs.

Installation Order

MetaCore must be installed first — it provisions the Authelia secrets and OIDC clients that the other apps depend on.

1. Install MetaCore → Creates Authelia secrets and OIDC clients (metasort, metafuse, metacore)
2. Install MetaSort, MetaFuse, MetaStremio in any order

Each app's pre-install-cmd checks for /DATA/AppData/metacore/authelia/secrets/client-<app>.plain and aborts with an error if MetaCore hasn't been installed.

Volume Permissions

Resource	MetaCore	MetaSort	MetaFuse	MetaStremio
/DATA/AppData/metacore/meta-core	rw	rw	rw	rw
/DATA/Downloads, /DATA/Media	ro (mounts at /files/watch/*)	— (WebDAV)	— (WebDAV)	— (WebDAV)
/DATA/AppData/<app>/cache	rw (own)	rw (own)	—	rw (own)
/DATA/AppData/metafuse/config	—	—	rw	—
/DATA/MetaFuse/Library	—	—	rw (FUSE mount)	—
/DATA/AppData/metacore/authelia/secrets	rw (creates)	ro (oauth sidecar)	ro (oauth sidecar)	—
pcs network (Yundera platform)	external	external	external	external

Developer Notes

Adding a New MetaMesh App

1. Add pre-install-cmd that checks for /DATA/AppData/metacore/authelia/secrets/client-<app>.plain
2. Bind-mount /DATA/AppData/metacore/meta-core:/meta-core:rw for leader info / service registration
3. Do NOT bind-mount user media — read files via MetaCore's WebDAV (http://metacore/webdav/*), URL discovered from /meta-core/locks/kv-leader.info
4. Join the pcs network as external: true (Yundera platform-managed; do not declare an app-private network)
5. Add an oauth2-proxy sidecar that reads its client secret from /DATA/AppData/metacore/authelia/secrets/client-<app>.plain
6. Discover Redis at runtime by reading /meta-core/locks/kv-leader.info

Debugging

# Check Redis data (Redis runs in MetaCore)
docker exec metacore redis-cli keys '*'

# Check leader election
cat /DATA/AppData/metacore/meta-core/locks/kv-leader.info

# Check service discovery
ls /DATA/AppData/metacore/meta-core/services/

# Check what's mounted into a service
docker exec metasort ls -la /files/watch/

Testing Locally

The MetaMesh dev environment (meta-root-v2/dev/) mirrors this architecture: direct bind mounts of ${DATA_WATCH_PATH}, ./cache/test/files, and ./cache/meta-sort/plugin-output at /files/watch, /files/test, /files/plugin — no parent named volume.