Sanitized mirror from private repository - 2026-04-24 08:27:14 UTC

2026-04-24 08:27:14 +00:00
commit 48bfce60e7
1450 changed files with 365038 additions and 0 deletions
--- a/docs/superpowers/specs/2026-04-24-pinchflat-design.md
+++ b/docs/superpowers/specs/2026-04-24-pinchflat-design.md
@@ -0,0 +1,146 @@
+# Pinchflat Test Deployment — Design
+
+**Date:** 2026-04-24
+**Status:** Approved, awaiting implementation plan
+**Scope:** Evaluate Pinchflat (YouTube auto-archiver) on Atlantis as a lightweight test before deciding whether to adopt permanently.
+
+## Goal
+
+Run Pinchflat on Atlantis long enough to evaluate its channel-subscription UX and download quality on real 4K monitors. Keep the test cheap to throw away: no SSO, no reverse proxy, no DNS entry, no Kuma monitor, no Portainer stack registration until we decide to keep it.
+
+## Non-Goals
+
+- Media-server integration (user does not use Jellyfin; no Plex integration planned for this test)
+- Authentik SSO / NPM proxy / `*.vish.gg` hostname / Kuma monitor — all deferred to a "promotion to prod" follow-up if we keep it
+- Exposure outside the LAN
+- GitOps / Portainer stack registration
+
+## Architecture
+
+Single container on Atlantis, port-published on the LAN. No dependencies on other services.
+
+```
+                   ┌──────────────────────────────────────┐
+                   │ Atlantis (Synology, 192.168.0.200)   │
+                   │                                      │
+   LAN browser ──► │  :8945  pinchflat                    │
+                   │         │                            │
+                   │         ├─► /config   (NVMe)         │
+                   │         │   /volume2/metadata/docker2│
+                   │         │     /pinchflat/config       │
+                   │         │                            │
+                   │         └─► /downloads (SATA)        │
+                   │             /volume1/data/media      │
+                   │               /youtube/               │
+                   └──────────────────────────────────────┘
+```
+
+## Components
+
+### 1. Container
+
+- **Image:** `ghcr.io/kieraneglin/pinchflat:latest`
+- **Container name:** `pinchflat`
+- **Network:** default bridge. Port published `8945:8945` (Pinchflat default, verified free on Atlantis via `ss -tlnp`).
+- **Not joined to `media2_net`** — nothing else talks to Pinchflat, no benefit to a static IP on the arr bridge.
+- **User/group:** PUID=1029, PGID=100 (Synology `dockerlimited:users` — matches existing media ownership so Plex/SMB can read the output folder later if we decide to integrate).
+- **Env:** `TZ=America/Los_Angeles`, `UMASK=022`.
+- **Security:** `security_opt: [no-new-privileges:true]`.
+- **Restart:** `unless-stopped`.
+- **Watchtower:** default (enabled). Fine for a test running `:latest`.
+- **Healthcheck:** HTTP GET `/` on port 8945, 30s interval (Pinchflat's web UI is the only interface).
+
+### 2. Storage
+
+- **Config volume:** `/volume2/metadata/docker2/pinchflat/config` → `/config` (NVMe, matches repo convention).
+- **Downloads volume:** `/volume1/data/media/youtube/` → `/downloads` (SATA RAID6, new folder alongside `movies/`, `tv/`, etc.).
+- No cache volume needed — Pinchflat writes directly to destination.
+
+### 3. Compose file
+
+- **Path:** `hosts/synology/atlantis/pinchflat/docker-compose.yml`
+- **Matches conventions observed in** `hosts/synology/atlantis/youtubedl.yaml` and `hosts/synology/atlantis/arr-suite/docker-compose.yml`.
+- Not referenced by any existing Portainer stack. Not in any `networks:` definition shared with other services.
+
+### 4. Pinchflat runtime defaults (configured in web UI on first launch)
+
+Applied globally; overridable per-channel.
+
+- **Output template:** `/downloads/{{ source_custom_name }}/{{ upload_yyyy_mm_dd }} - {{ title }}.{{ ext }}`
+  - Produces `/downloads/Veritasium/2024-03-12 - Why planes don't fly faster.mkv` etc.
+  - One folder per channel, date-prefixed files for chronological sort, no fake S01E01 naming.
+- **Resolution cap:** 4K (best available up to 2160p). User has 4K monitors; 4K channels get 4K, others fall back naturally.
+- **Container format:** MKV (required for clean VP9/AV1 playback — YouTube does not encode 4K in H.264).
+- **Thumbnails:** on (cheap, useful in file managers).
+- **Subtitles:** on (any available language, SRT sidecar files).
+- **Chapters:** on (embedded in MKV).
+- **NFO files:** off (only useful for Plex/Kodi/Jellyfin; not needed here).
+
+## Deployment & Test Workflow
+
+1. Create branch `feat/pinchflat` off `main`.
+2. Add `hosts/synology/atlantis/pinchflat/docker-compose.yml` and a stub `docs/services/individual/pinchflat.md` (~20 lines: what it is, current test status, URL).
+3. Commit, push branch.
+4. SSH to Atlantis, clone/checkout the branch to a throwaway working copy under `/volume1/homes/vish/pinchflat-test/`.
+5. `docker compose up -d` from the working copy.
+6. Pre-create `/volume1/data/media/youtube/` with `dockerlimited:users` ownership (or let Pinchflat create it on first download — either works).
+7. Open `http://192.168.0.200:8945` in a browser, walk through initial setup, apply the defaults from §4.
+8. Subscribe to 2–5 test channels. Let it run for several days.
+9. Decide:
+   - **Keep:** merge branch to `main`, register new Portainer GitOps stack pointing at the committed compose path, expand docs, stop the hand-run container, re-`up` via Portainer.
+   - **Drop:** `docker compose down -v` on Atlantis, `rm -rf /volume2/metadata/docker2/pinchflat /volume1/data/media/youtube`, delete the branch.
+
+## Data Flow
+
+```
+YouTube ──► Pinchflat (yt-dlp) ──► /downloads/<Channel>/<date> - <title>.mkv
+                │
+                └─► /config/pinchflat.db  (SQLite: subscriptions, download history)
+```
+
+No downstream consumers during the test. Files live on the filesystem; user browses via SMB / file manager / direct playback.
+
+## Error Handling
+
+- **Download failures** (age-restricted, geo-blocked, deleted videos): Pinchflat surfaces these in its web UI with retry buttons. No external alerting during the test.
+- **Disk fill:** `/volume1/data` has ample headroom, but 4K with many channels can grow fast. If it becomes a concern, lower the global cap to 1080p or set per-channel caps.
+- **Container crash:** `restart: unless-stopped` brings it back. No monitoring during the test phase — we'll notice if the UI doesn't load.
+- **`:latest` breaking change:** Watchtower enabled. If an update breaks something, we roll back by pinning to a prior digest in the compose file.
+
+## Testing
+
+Manual, UI-driven:
+
+- **Smoke:** container comes up, web UI loads, ingests a single video from a pasted URL.
+- **Subscription:** channel subscription polls correctly, new uploads appear within the polling interval.
+- **Quality:** 4K-capable channel produces a 2160p MKV; 1080p-only channel produces a 1080p MKV.
+- **Sidecar files:** subtitles and thumbnails present next to the MKV.
+- **Permissions:** output files are `dockerlimited:users`, readable via SMB.
+- **Persistence:** restart container, state survives.
+
+## Open Questions
+
+None — design approved.
+
+## Promotion Path (if kept)
+
+Out of scope for this spec, but the follow-up to "keep" would include:
+- Register GitOps stack in Portainer from the committed compose path
+- Add Authentik proxy provider + NPM proxy host for `pinchflat.vish.gg`
+- Add Kuma monitor (HTTP `http://192.168.0.200:8945`)
+- Pin image to a specific version digest instead of `:latest`
+- Expand `docs/services/individual/pinchflat.md` with full operational runbook
+
+## Rollback Plan
+
+Throw-away test. Rollback is:
+
+```bash
+ssh atlantis
+cd /volume1/homes/vish/pinchflat-test
+docker compose down -v
+sudo rm -rf /volume2/metadata/docker2/pinchflat /volume1/data/media/youtube
+cd ~ && rm -rf pinchflat-test
+```
+
+Then `git branch -D feat/pinchflat` and `git push origin --delete feat/pinchflat`. Zero impact on any production stack since nothing references this compose file.