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

docs/superpowers/plans/2026-04-24-pinchflat.md

@@ -0,0 +1,410 @@
+# Pinchflat Test Deployment Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Deploy Pinchflat (YouTube auto-archiver) on Atlantis via a hand-run docker compose on a feature branch, so the user can evaluate it before committing to production promotion.
+
+**Architecture:** Single `ghcr.io/kieraneglin/pinchflat:latest` container, port-published on `8945` on Atlantis's LAN IP. Config on Atlantis NVMe (`/volume2/metadata/docker2/pinchflat/config`), downloads on SATA array (`/volume1/data/media/youtube`). No SSO, no reverse proxy, no Kuma monitor, no Portainer stack — purely a branch-based hand-run test.
+
+**Tech Stack:** Docker Compose, Synology DSM (Atlantis NAS), SSH to `vish@atlantis`, git.
+
+**Reference spec:** `docs/superpowers/specs/2026-04-24-pinchflat-design.md`
+
+---
+
+## File Structure
+
+Files added to the repo on branch `feat/pinchflat`:
+
+- `hosts/synology/atlantis/pinchflat/docker-compose.yml` — the single-service compose definition
+- `docs/services/individual/pinchflat.md` — brief stub (purpose, URL, test status), following repo convention at `docs/services/individual/<service>.md`
+
+Non-tracked host state created on Atlantis:
+
+- `/volume2/metadata/docker2/pinchflat/config/` — persistent SQLite + YAML config
+- `/volume1/data/media/youtube/` — download target folder
+- `/volume1/homes/vish/pinchflat-test/` — throwaway working copy of the branch
+
+No modifications to existing files. No Portainer stack registration.
+
+---
+
+## Task 1: Pre-flight checks on Atlantis
+
+**Files:** None (verification only)
+
+- [ ] **Step 1: Confirm port 8945 is free on Atlantis**
+
+Run:
+```bash
+ssh vish@atlantis 'ss -tlnp 2>/dev/null | grep -E ":8945\b" || echo "port 8945 free"'
+```
+
+Expected: `port 8945 free`
+
+If a process is listening on 8945, stop and re-plan — pick a different host port (e.g. 8946) and update the compose file in Task 2 accordingly.
+
+- [ ] **Step 2: Confirm media root exists and ownership convention**
+
+Run:
+```bash
+ssh vish@atlantis 'ls -ld /volume1/data/media /volume2/metadata/docker2'
+```
+
+Expected output includes two directories owned by a user account, with `/volume1/data/media` containing existing media subfolders (movies, tv, anime, etc.).
+
+- [ ] **Step 3: Confirm Docker daemon is running on Atlantis**
+
+Run:
+```bash
+ssh vish@atlantis 'docker ps --format "table {{.Names}}\t{{.Status}}" | head -5'
+```
+
+Expected: a table listing at least a handful of running containers (plex, sonarr, etc.). If Docker isn't responding, stop and investigate before proceeding.
+
+---
+
+## Task 2: Create feature branch and compose file
+
+**Files:**
+- Create: `hosts/synology/atlantis/pinchflat/docker-compose.yml`
+
+- [ ] **Step 1: Create branch off main**
+
+Run from the repo root `/home/homelab/organized/repos/homelab`:
+```bash
+git checkout main && git pull --ff-only && git checkout -b feat/pinchflat
+```
+
+Expected: branch `feat/pinchflat` checked out, working tree clean except for the pre-existing untracked items (`.secrets.baseline` modifications, `data/expenses.csv`, `.superpowers/`, `backups/`).
+
+- [ ] **Step 2: Create the compose directory**
+
+Run:
+```bash
+mkdir -p hosts/synology/atlantis/pinchflat
+```
+
+- [ ] **Step 3: Write `hosts/synology/atlantis/pinchflat/docker-compose.yml`**
+
+Full file contents:
+
+```yaml
+# Pinchflat - YouTube auto-archiver (test deployment)
+# Port: 8945
+# Docs: https://github.com/kieraneglin/pinchflat
+# Scope: lightweight evaluation on Atlantis. No SSO, no reverse proxy, no Kuma.
+# See: docs/superpowers/specs/2026-04-24-pinchflat-design.md
+version: "3.8"
+
+services:
+  pinchflat:
+    image: ghcr.io/kieraneglin/pinchflat:latest
+    container_name: pinchflat
+
+    environment:
+      - PUID=1029
+      - PGID=100
+      - TZ=America/Los_Angeles
+      - UMASK=022
+
+    ports:
+      - "8945:8945"
+
+    volumes:
+      - /volume2/metadata/docker2/pinchflat/config:/config
+      - /volume1/data/media/youtube:/downloads
+
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO /dev/null http://127.0.0.1:8945/ 2>/dev/null || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+
+    security_opt:
+      - no-new-privileges:true
+
+    restart: unless-stopped
+```
+
+- [ ] **Step 4: Validate the YAML**
+
+Run from the repo root:
+```bash
+python3 -c "import yaml; yaml.safe_load(open('hosts/synology/atlantis/pinchflat/docker-compose.yml'))" && echo "YAML OK"
+```
+
+Expected: `YAML OK`
+
+If parsing fails, fix the indentation/syntax before proceeding. Do not use `sed` to edit — re-run the Write step with the full corrected file.
+
+---
+
+## Task 3: Write the docs stub
+
+**Files:**
+- Create: `docs/services/individual/pinchflat.md`
+
+- [ ] **Step 1: Write the doc stub**
+
+Full file contents:
+
+````markdown
+# Pinchflat
+
+YouTube channel auto-archiver. Subscribes to channels, polls for new uploads, downloads via yt-dlp, stores locally with metadata/subtitles/chapters.
+
+## Status
+
+**Test deployment as of 2026-04-24.** Running on Atlantis via hand-run `docker compose` on branch `feat/pinchflat`. Not yet registered in Portainer, not yet behind Authentik / NPM / Kuma.
+
+See `docs/superpowers/specs/2026-04-24-pinchflat-design.md` for design rationale and promotion path.
+
+## Access
+
+- **Web UI:** http://192.168.0.200:8945 (LAN only)
+- **Host:** Atlantis
+- **Image:** `ghcr.io/kieraneglin/pinchflat:latest`
+
+## Paths on Atlantis
+
+- **Compose:** `/volume1/homes/vish/pinchflat-test/hosts/synology/atlantis/pinchflat/docker-compose.yml` (during test)
+- **Config:** `/volume2/metadata/docker2/pinchflat/config`
+- **Downloads:** `/volume1/data/media/youtube/<Channel>/<YYYY-MM-DD> - <Title>.mkv`
+
+## Runtime defaults (configure in web UI on first launch)
+
+- Output template: `/downloads/{{ source_custom_name }}/{{ upload_yyyy_mm_dd }} - {{ title }}.{{ ext }}`
+- Resolution cap: 2160p (4K)
+- Container format: MKV (required for VP9/AV1 4K streams)
+- Thumbnails: on
+- Subtitles: on
+- Chapters: on
+- NFO files: off
+
+## Operations
+
+### Start / stop (during test phase)
+
+```bash
+ssh vish@atlantis
+cd /volume1/homes/vish/pinchflat-test
+docker compose up -d     # start
+docker compose logs -f   # tail logs
+docker compose down      # stop (data preserved)
+```
+
+### Full teardown (abandon test)
+
+```bash
+ssh vish@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 /volume1/homes/vish/pinchflat-test
+```
+
+Then on the workstation:
+```bash
+git branch -D feat/pinchflat
+git push origin --delete feat/pinchflat   # if pushed
+```
+
+## Promotion to production (if keeping)
+
+1. Merge `feat/pinchflat` → `main`.
+2. Register new Portainer GitOps stack pointing at `hosts/synology/atlantis/pinchflat/docker-compose.yml`.
+3. Stop the hand-run container, re-up via Portainer.
+4. Add NPM proxy host `pinchflat.vish.gg` + Authentik proxy provider.
+5. Add Kuma HTTP monitor against `http://192.168.0.200:8945`.
+6. Pin the image to a specific digest instead of `:latest`.
+7. Expand this doc with operational runbook (channel subscription process, troubleshooting, log locations).
+````
+
+- [ ] **Step 2: Verify the doc renders as expected Markdown**
+
+Run:
+```bash
+head -5 docs/services/individual/pinchflat.md && echo "---" && wc -l docs/services/individual/pinchflat.md
+```
+
+Expected: the first line is `# Pinchflat`, line count is around 60–70.
+
+---
+
+## Task 4: Commit and push the branch
+
+**Files:** Both files from Task 2 and Task 3.
+
+- [ ] **Step 1: Stage the two new files only**
+
+Explicitly avoid staging the pre-existing dirty working-tree items (`.secrets.baseline`, `data/expenses.csv`, `.superpowers/`, `backups/`).
+
+Run:
+```bash
+git add hosts/synology/atlantis/pinchflat/docker-compose.yml docs/services/individual/pinchflat.md
+git status --short
+```
+
+Expected: only the two new files appear in the "to be committed" section. Other items remain in the unstaged/untracked section untouched.
+
+- [ ] **Step 2: Commit**
+
+Run:
+```bash
+git commit -m "feat(pinchflat): add test deployment compose + docs stub
+
+Hand-run docker compose on Atlantis port 8945 for evaluating Pinchflat as a
+YouTube auto-archiver. No SSO/NPM/Kuma/Portainer during the test phase.
+
+See docs/superpowers/specs/2026-04-24-pinchflat-design.md for design and
+promotion path."
+```
+
+Expected: a commit hook chain runs (trim whitespace, check yaml, yamllint, docker-compose syntax check, detect-secrets). All should pass. Per CLAUDE.md, never add `Co-Authored-By` lines.
+
+If yamllint fails on the new compose file, read the error, fix the compose file inline with Edit (not sed), re-validate per Task 2 Step 4, then `git add` + `git commit --amend --no-edit` is acceptable here since the commit has not been pushed yet.
+
+- [ ] **Step 3: Push the branch**
+
+Run:
+```bash
+git push -u origin feat/pinchflat
+```
+
+Expected: branch published to Gitea. Output shows tracking established.
+
+---
+
+## Task 5: Deploy on Atlantis
+
+**Files:** None in the repo; creates host directories and launches the container.
+
+- [ ] **Step 1: Create the config and download directories with correct ownership**
+
+Pinchflat runs as `PUID=1029 PGID=100` (Synology `dockerlimited:users`). Pre-create the dirs so there's no first-boot permission confusion.
+
+Run:
+```bash
+ssh vish@atlantis 'sudo mkdir -p /volume2/metadata/docker2/pinchflat/config /volume1/data/media/youtube && sudo chown -R 1029:100 /volume2/metadata/docker2/pinchflat /volume1/data/media/youtube && ls -ld /volume2/metadata/docker2/pinchflat /volume1/data/media/youtube'
+```
+
+Expected: both directories exist and are owned by `dockerlimited:users` (which may display as `1029:users` depending on DSM's /etc/passwd).
+
+- [ ] **Step 2: Clone the branch to a throwaway working copy on Atlantis**
+
+Run:
+```bash
+ssh vish@atlantis 'mkdir -p /volume1/homes/vish/pinchflat-test && cd /volume1/homes/vish/pinchflat-test && git clone --branch feat/pinchflat --depth 1 https://git.vish.gg/vish/homelab.git . && ls hosts/synology/atlantis/pinchflat/'
+```
+
+Expected: a single `docker-compose.yml` listed under the pinchflat directory. If the git clone fails (auth or network), fall back to `scp` of the single compose file:
+```bash
+scp hosts/synology/atlantis/pinchflat/docker-compose.yml vish@atlantis:/volume1/homes/vish/pinchflat-test/docker-compose.yml
+```
+
+(in which case the `docker compose` commands in later steps should be run directly from `/volume1/homes/vish/pinchflat-test/` rather than the nested path)
+
+- [ ] **Step 3: Pull the image**
+
+Run:
+```bash
+ssh vish@atlantis 'cd /volume1/homes/vish/pinchflat-test/hosts/synology/atlantis/pinchflat && docker compose pull'
+```
+
+Expected: image `ghcr.io/kieraneglin/pinchflat:latest` pulls successfully. If pull fails on auth (ghcr.io rate-limit), add `docker login ghcr.io` with a PAT and retry.
+
+- [ ] **Step 4: Start the container**
+
+Run:
+```bash
+ssh vish@atlantis 'cd /volume1/homes/vish/pinchflat-test/hosts/synology/atlantis/pinchflat && docker compose up -d'
+```
+
+Expected: `Container pinchflat  Started`. No errors.
+
+- [ ] **Step 5: Verify container status**
+
+Run:
+```bash
+ssh vish@atlantis 'docker ps --filter name=pinchflat --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"'
+```
+
+Expected: single row showing `pinchflat  Up N seconds (health: starting)  0.0.0.0:8945->8945/tcp, :::8945->8945/tcp`. Wait ~60 seconds after the first `up` so the healthcheck can transition from `starting` to `healthy`.
+
+---
+
+## Task 6: Smoke test
+
+**Files:** None (evaluation only)
+
+- [ ] **Step 1: Confirm the web UI responds**
+
+Run from the workstation:
+```bash
+curl -s -o /dev/null -w "%{http_code}\n" http://192.168.0.200:8945/
+```
+
+Expected: `200` (Pinchflat serves its dashboard at `/`). If you get `000` (connection refused), wait 30 seconds and retry — the app takes a moment to bind after container start.
+
+- [ ] **Step 2: Tail logs for any obvious errors**
+
+Run:
+```bash
+ssh vish@atlantis 'docker logs pinchflat --tail 50 2>&1 | grep -iE "error|fatal|panic" | head -20 || echo "no errors in recent logs"'
+```
+
+Expected: `no errors in recent logs`, or if any errors appear, assess whether they're benign (e.g. migration notices) vs blocking.
+
+- [ ] **Step 3: Check container healthcheck transitioned to healthy**
+
+Run:
+```bash
+ssh vish@atlantis 'docker inspect pinchflat --format "{{.State.Health.Status}}"'
+```
+
+Expected: `healthy`. If still `starting` after 2 minutes, check logs for why the web server isn't responding. If `unhealthy`, something is wrong — stop and debug before handing off.
+
+- [ ] **Step 4: Confirm config and download volumes wrote correctly**
+
+Run:
+```bash
+ssh vish@atlantis 'ls -la /volume2/metadata/docker2/pinchflat/config/ | head -10 && echo "---" && ls -la /volume1/data/media/youtube/'
+```
+
+Expected: the config dir now contains Pinchflat's initial files (e.g. database file, YAML config). The downloads dir may still be empty — that's fine, it only populates after the user subscribes to a channel.
+
+- [ ] **Step 5: Hand off to user for UI walk-through**
+
+Report to the user:
+- URL: `http://192.168.0.200:8945`
+- Container state: running + healthy
+- Next step is user-driven: open the URL, walk through first-run setup, apply the defaults from §4 of the spec (output template, 4K cap, MKV container, thumbnails/subtitles/chapters on, NFO off), subscribe to 2–5 test channels.
+
+Do NOT mark the plan as complete at this step. The user drives the evaluation window; the plan is complete when the user makes the keep/drop decision.
+
+---
+
+## Task 7 (deferred): Keep-or-drop decision
+
+**Trigger:** User signals "keep" or "drop" after evaluation window.
+
+**If KEEP:**
+- Open follow-up plan for promotion (register Portainer GitOps stack, add NPM + Authentik + Kuma, pin image digest, expand docs).
+- Out of scope for this plan.
+
+**If DROP:**
+- [ ] Run the teardown block from `docs/services/individual/pinchflat.md` (Full teardown section).
+- [ ] Delete the remote branch: `git push origin --delete feat/pinchflat`.
+- [ ] Delete the local branch: `git branch -D feat/pinchflat`.
+- [ ] Optionally delete the two repo files with a follow-up commit on main, or leave the branch deleted and nothing ever landed on main — either is fine.
+
+---
+
+## Self-review notes
+
+- **Spec coverage:** Every spec section (architecture, components, storage, runtime defaults, deployment workflow, error handling, testing, rollback) maps to a task or is explicitly deferred. ✓
+- **Placeholder scan:** No TBDs. No "similar to Task N" shortcuts. Every compose field and command is literal. ✓
+- **Type consistency:** Paths match across tasks (`/volume1/data/media/youtube`, `/volume2/metadata/docker2/pinchflat/config`, `/volume1/homes/vish/pinchflat-test`, port `8945`). Ownership `1029:100` consistent. ✓
+- **Known fuzziness:** "60-70 lines" for the doc stub is approximate; the exact line count depends on final whitespace. Not a blocker.