zima-apps/.kilo/plans/1776548369772-nimble-planet.md

Plan: Add Snacks app to zima-apps

Context

apps.md lists "Snacks" (https://github.com/derekshreds/snacks) as a pending app. It is an automated video library encoder with hardware acceleration (NVENC, QSV, VAAPI, AMF).

This plan has two parts:

1. Create the Snacks app definition
2. Update apps.md with agent instructions for future additions

---

Part 1: Create Apps/snacks/

Steps

1. Create Apps/snacks/ directory from _template

2. docker-compose.yaml — adapt upstream deploy-compose.yml:

   Field	Upstream value	ZimaOS target
   name	n/a	snacks
   image	derekshreds/snacks-docker:latest	Pinned version — fetch latest release tag from GitHub, verify manifest exists
   network_mode	host	Keep host — required for cluster UDP broadcast discovery
   privileged	true	Keep true — required for /dev/dri access on QNAP/ZimaOS
   devices	/dev/dri:/dev/dri	Keep — VAAPI/QSV hardware acceleration
   ports	none (host mode)	Add 6767:6767 for web UI
   volumes	QNAP-specific paths	Parameterize as /DATA/AppData/$AppID/...
   environment	QNAP-specific ffmpeg path	Use default ffmpeg path; make jellyfin-ffmpeg path configurable

   Security baseline (MUST):

   • security_opt: ["no-new-privileges:true"]
   • cap_drop: ["ALL"]
   • deploy.resources.reservations set to appropriate value

   High-risk settings that MUST be documented in README:

   • network_mode: host — required for cluster UDP broadcast
   • privileged: true — required for /dev/dri access
   • Device mount /dev/dri — GPU acceleration

3. README.md — document:

   • Purpose: automated video library encoder with hardware acceleration
   • Port: 6767 (web UI)
   • Volumes: media library, logs, config
   • High-risk settings with justification, alternatives evaluated, and risks
   • Hardware acceleration options (VAAPI, QSV, NVENC)
   • Cluster mode (UDP broadcast requirement)
   • Health check endpoint

4. Image pinning: Before merge, verify the image tag exists in Docker Hub registry (manifest check)

5. Run validation: ./scripts/validate-appstore.sh

6. Optional: HOW_TO_VERIFY.md with integration test cases

Risk Assessment

• High risk due to network_mode: host, privileged: true, and device mounts
• Must document all three in README per AGENTS.md §3
• Image must be pinned — no :latest

Branch name

snacks/initial/add-video-encoder

---

Part 2: Update apps.md

Changes

Replace current content with a table format that includes:

• Done/pending checkbox
• App name
• Source URL
• Brief description
• Agent instructions column (how to pick up this item)

The file should serve as an agent-facing backlog — clear enough that an agent can read it, understand what is needed, and execute without additional prompting.

Suggested format

## Backlog

| # | Done | Name | Source | What | Agent instructions |
|---|---|---|---|---|---|
| 1 | [ ] | Snacks | https://github.com/derekshreds/snacks | Automated video library encoder | Pick up, follow AGENTS.md §9 workflow, branch `snacks/initial/add-video-encoder` |

## Adding a new app

1. Copy `Apps/_template/` → `Apps/<app-id>/`
2. Set `name` in compose (lowercase + hyphen only)
3. Pin image to explicit version/tag (no `:latest`)
4. Add `x-casaos` metadata
5. Write `README.md` with purpose, ports, volumes, and risk justifications
6. Validate: `./scripts/validate-appstore.sh`
7. Run final validation before release: `./scripts/validate-appstore.sh --enforce-risk-docs`

---

Verification

• docker-compose -f Apps/snacks/docker-compose.yaml config passes (no syntax errors)
• No :latest references
• x-casaos metadata complete
• README documents all high-risk settings with justification
• ./scripts/validate-appstore.sh reports Validation OK