From 7eab41eaba30b2072398b00a3ee254d0cbcbca6b Mon Sep 17 00:00:00 2001 From: Lucas Berger Date: Mon, 9 Feb 2026 08:11:54 -0500 Subject: [PATCH] docs: define milestone v1.4 requirements --- .planning/PROJECT.md | 13 +++-- .planning/REQUIREMENTS.md | 110 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 119 insertions(+), 4 deletions(-) create mode 100644 .planning/REQUIREMENTS.md diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md index adb46dc..7182d62 100644 --- a/.planning/PROJECT.md +++ b/.planning/PROJECT.md @@ -56,11 +56,12 @@ When you get a container update notification or notice a service is down, you ca **Goal:** Replace Docker socket proxy with Unraid's GraphQL API for all container operations, remove all proxy artifacts, and update documentation. **Target features:** -- All container operations via Unraid GraphQL API (status, start, stop, restart, update, logs) -- Remove docker-socket-proxy references from workflows, credentials, and n8n container config -- Clean up all proxy-related artifacts (nodes, variables, network references) +- All container operations via Unraid GraphQL API (status, start, stop, restart, update) +- Remove container logs feature (not valuable enough to justify hybrid architecture) +- Remove docker-socket-proxy container entirely (no hybrid architecture) +- Remove all proxy-related artifacts from workflows, credentials, n8n container config - Documentation fully updated for Unraid API-native architecture (README, ARCHITECTURE.md, CLAUDE.md) -- Migration/cleanup instructions for removing the proxy container +- Cleanup instructions for removing the proxy container ### Out of Scope @@ -70,6 +71,8 @@ When you get a container update notification or notice a service is down, you ca - Proactive monitoring/notifications — bot is reactive (you ask, it answers) - Offline mode — real-time Docker API access is core to functionality - Ring buffer / persistent debug logging — n8n static data is execution-scoped, not workflow-scoped +- Container logs via Telegram bot — removed in v1.4 to eliminate hybrid architecture (Docker proxy + Unraid API); not valuable enough to justify complexity +- Real-time container stats — requires WebSocket infrastructure, defer to future ## Current State @@ -132,6 +135,8 @@ When you get a container update notification or notice a service is down, you ca | myunraid.net cloud relay for Unraid API | Direct LAN IP fails (nginx strips auth headers on redirect) | ✓ Good | | Environment variables for Unraid API auth | More reliable than n8n Header Auth credential system for GraphQL | ✓ Good | | Descope v1.3 to Phase 14 only | Phases 15-16 superseded by v1.4 Unraid API Native approach | ✓ Good | +| Remove container logs feature in v1.4 | Not valuable enough to justify hybrid architecture (Docker proxy for logs + Unraid API for everything else) | — Pending | +| Remove docker-socket-proxy entirely | Clean single-API architecture, no hybrid routing complexity | — Pending | --- *Last updated: 2026-02-09 after v1.4 milestone started* diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md new file mode 100644 index 0000000..46a84da --- /dev/null +++ b/.planning/REQUIREMENTS.md @@ -0,0 +1,110 @@ +# Requirements: Unraid Docker Manager + +**Defined:** 2026-02-09 +**Core Value:** When you get a container update notification or notice a service is down, you can immediately investigate and act from your phone. + +## v1.4 Requirements + +Requirements for v1.4 Unraid API Native milestone. Each maps to roadmap phases. + +### API Migration + +- [ ] **API-01**: Container status query works via Unraid GraphQL API (replaces Docker REST API) +- [ ] **API-02**: Container start works via Unraid GraphQL mutation +- [ ] **API-03**: Container stop works via Unraid GraphQL mutation +- [ ] **API-04**: Container restart works via sequential stop+start GraphQL mutations (no native restart) +- [ ] **API-05**: Container update works via single `updateContainer` GraphQL mutation (replaces 5-step Docker flow) +- [ ] **API-06**: Batch container update works via `updateContainers` GraphQL mutation +- [ ] **API-07**: "Update all :latest" works via Unraid GraphQL API with :latest filtering +- [ ] **API-08**: Unraid update badges clear automatically after bot-initiated updates (no manual sync) + +### Infrastructure + +- [ ] **INFRA-01**: Container ID translation layer maps names to Unraid PrefixedID format (129-char `server_hash:container_hash`) +- [ ] **INFRA-02**: Callback data encoding works with Unraid PrefixedIDs within Telegram's 64-byte limit +- [ ] **INFRA-03**: GraphQL response normalization transforms Unraid API responses to match workflow contracts +- [ ] **INFRA-04**: GraphQL error handling standardized (check `response.errors[]`, handle HTTP 304 "already in state") +- [ ] **INFRA-05**: Timeout configuration accounts for myunraid.net cloud relay latency (200-500ms per request) + +### Cleanup + +- [ ] **CLN-01**: Docker socket proxy references removed from all workflow JSON files +- [ ] **CLN-02**: Container logs feature removed from workflows (text command, inline keyboard, sub-workflow) +- [ ] **CLN-03**: n8n-logs.json sub-workflow removed or emptied +- [ ] **CLN-04**: docker-socket-proxy container can be safely removed (no remaining dependencies) +- [ ] **CLN-05**: n8n container config cleaned (remove proxy network, socket-related env vars) +- [ ] **CLN-06**: "unraid" test command updated or removed (v1.3 connectivity test) + +### Documentation + +- [ ] **DOC-01**: README.md updated to reflect Unraid API-native architecture (remove proxy references) +- [ ] **DOC-02**: ARCHITECTURE.md updated with Unraid GraphQL API contracts and patterns +- [ ] **DOC-03**: CLAUDE.md updated with new API patterns and removed proxy recipes +- [ ] **DOC-04**: Cleanup instructions documented for removing docker-socket-proxy container + +## Future Requirements + +Deferred to future release. Tracked but not in current roadmap. + +### Container Logs (Removed in v1.4) + +- **LOGS-01**: Container logs via Unraid GraphQL API (if API adds logs support in future) +- **LOGS-02**: Container logs via SSH fallback (alternative to Docker socket proxy) + +### Advanced Features + +- **ADV-01**: Real-time container stats via GraphQL subscription +- **ADV-02**: Container autostart configuration via bot +- **ADV-03**: Port conflict detection and reporting +- **ADV-04**: Direct LAN fallback if myunraid.net relay unavailable + +## Out of Scope + +Explicitly excluded. Documented to prevent scope creep. + +| Feature | Reason | +|---------|--------| +| Container logs via Telegram | Removed in v1.4 — not valuable enough to justify hybrid architecture (Docker proxy + Unraid API) | +| GraphQL subscriptions (WebSocket) | Requires infrastructure n8n doesn't natively support, high complexity for low value | +| Dual API support (Docker + Unraid) | No hybrid architecture — single API simplifies maintenance and debugging | +| New container deployment | Manage existing only, deployment rarely needed from mobile | +| Natural language understanding | Simple keyword matching works, Claude API adds unnecessary complexity | + +## Traceability + +Which phases cover which requirements. Updated during roadmap creation. + +| Requirement | Phase | Status | +|-------------|-------|--------| +| INFRA-01 | — | Pending | +| INFRA-02 | — | Pending | +| INFRA-03 | — | Pending | +| INFRA-04 | — | Pending | +| INFRA-05 | — | Pending | +| API-01 | — | Pending | +| API-02 | — | Pending | +| API-03 | — | Pending | +| API-04 | — | Pending | +| API-05 | — | Pending | +| API-06 | — | Pending | +| API-07 | — | Pending | +| API-08 | — | Pending | +| CLN-01 | — | Pending | +| CLN-02 | — | Pending | +| CLN-03 | — | Pending | +| CLN-04 | — | Pending | +| CLN-05 | — | Pending | +| CLN-06 | — | Pending | +| DOC-01 | — | Pending | +| DOC-02 | — | Pending | +| DOC-03 | — | Pending | +| DOC-04 | — | Pending | + +**Coverage:** +- v1.4 requirements: 23 total +- Mapped to phases: 0 +- Unmapped: 23 ⚠️ + +--- +*Requirements defined: 2026-02-09* +*Last updated: 2026-02-09 after initial definition*