feat: v1.3 Unraid Update Status Sync

Unraid GraphQL API foundation — connectivity, authentication, and container ID format verified for native Unraid API integration. Phase 14: Unraid API Access (2 plans, 4 tasks) - Established Unraid GraphQL API connectivity via myunraid.net cloud relay - Dual credential storage (.env.unraid-api + n8n env vars) - Container ID format: {server_hash}:{container_hash} (128-char SHA256 pair) - Complete API contract documented in ARCHITECTURE.md - "unraid" test command added to Telegram bot Phases 15-16 dropped (superseded by v1.4 Unraid API Native). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-09 07:47:31 -05:00
parent ff0773b84b
commit 903e73d616
14 changed files with 1018 additions and 205 deletions
@@ -0,0 +1,67 @@
+# Milestone v1.3: Unraid Update Status Sync
+
+**Status:** ✅ SHIPPED 2026-02-09 (descoped)
+**Phases:** 14 (1 phase, 2 plans)
+**Original scope:** Phases 14-16 — Phases 15-16 dropped (superseded by v1.4 Unraid API Native)
+
+## Overview
+
+Established Unraid GraphQL API connectivity from the n8n container, enabling native Unraid API integration. Originally scoped to sync container update status back to Unraid after bot-initiated updates (Phases 14-16), but descoped to Phase 14 only when the user decided to replace the Docker socket proxy entirely with Unraid's API — making the sync approach unnecessary.
+
+## Phases
+
+### Phase 14: Unraid API Access
+
+**Goal:** Validate GraphQL API connectivity and establish secure authentication from n8n container to Unraid host.
+
+**Depends on:** Nothing (first phase of milestone)
+
+**Requirements:** INFRA-01, INFRA-02, INFRA-03
+
+**Success Criteria** (what must be TRUE):
+1. n8n container can successfully reach Unraid's GraphQL API endpoint via HTTP request
+2. Unraid API key exists with Docker update permission and is securely stored in gitignored `.env.unraid-api`
+3. Container ID format is documented and verified via test GraphQL query
+4. Test GraphQL query can list containers and return expected data structure
+
+**Plans:** 2 plans
+
+Plans:
+- [x] 14-01-PLAN.md — Credential infrastructure and Unraid GraphQL test workflow nodes
+- [x] 14-02-PLAN.md — GraphQL API contract documentation and connectivity verification
+
+### Phase 15: Single Container Sync (DROPPED)
+
+**Status:** Superseded — v1.4 Unraid API Native eliminates need for separate sync.
+
+**Original Goal:** After bot updates a single container via text command or inline keyboard, Unraid automatically clears the "update available" badge without user intervention.
+
+### Phase 16: Batch Sync & Documentation (DROPPED)
+
+**Status:** Superseded — v1.4 documentation will cover the full Unraid API migration.
+
+**Original Goal:** Batch update operations sync all updated containers to Unraid efficiently, and users can set up Unraid sync integration from documentation alone.
+
+## Milestone Summary
+
+**Key Decisions:**
+- Use myunraid.net cloud relay URL instead of direct LAN IP (nginx redirect strips auth headers)
+- Environment variables (UNRAID_HOST, UNRAID_API_KEY) instead of n8n Header Auth credentials (more reliable)
+- Dual credential storage (.env.unraid-api + n8n env vars) mirroring existing .env.n8n-api pattern
+- Descope to Phase 14 only — Phases 15-16 superseded by v1.4 Unraid API Native approach
+
+**Issues Resolved:**
+- Unraid GraphQL API connectivity verified (myunraid.net cloud relay is the working approach)
+- Container ID format discovered: `{server_hash}:{container_hash}` (128-char SHA256 pair)
+- Schema corrections: `isUpdateAvailable` does not exist, `state` is UPPERCASE, `names` prefixed with `/`
+
+**Issues Deferred:**
+- SYNC requirements (all 6) — superseded by v1.4 Unraid API Native
+- Documentation requirements (DOC-01, DOC-02) — deferred to v1.4
+
+**Technical Debt Incurred:**
+- None — clean foundation for v1.4
+
+---
+
+_For current project status, see .planning/ROADMAP.md_