# 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.