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,142 @@
+---
+phase: 14-unraid-api-access
+plan: 02
+subsystem: infrastructure
+tags: [unraid-graphql, architecture-docs, network-access, authentication]
+dependency-graph:
+  requires:
+    - phase: 14-01
+      provides: [unraid-api-credentials, unraid-graphql-test-nodes]
+  provides:
+    - Complete Unraid GraphQL API contract documentation
+    - Container ID format specification (server_hash:container_hash)
+    - Production-verified network access patterns (myunraid.net cloud relay)
+    - Authentication pattern (environment variables)
+    - Schema corrections (state uppercase, names prefixed, isUpdateAvailable does not exist)
+  affects: [phase-15-update-sync, unraid-api-integration]
+tech-stack:
+  added: []
+  patterns: [myunraid-cloud-relay, environment-variable-auth, graphql-schema-verification]
+key-files:
+  created: []
+  modified:
+    - ARCHITECTURE.md
+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 credentials (more reliable)"
+  - "Document schema discrepancies between research and actual API (isUpdateAvailable does not exist)"
+metrics:
+  duration: 71 seconds
+  completed: 2026-02-08T18:01:16Z
+  tasks: 2
+  files_changed: 1
+  commits: 2
+---
+
+# Phase 14 Plan 02: Unraid API Connectivity Verification Summary
+
+**Production-verified Unraid GraphQL API documentation with container ID format, myunraid.net network access pattern, and schema corrections**
+
+## Performance
+
+- **Duration:** 71 seconds (1 min 11 sec)
+- **Started:** 2026-02-08T17:59:25Z
+- **Completed:** 2026-02-08T18:01:16Z
+- **Tasks:** 2 (1 complete in 14-01, 1 continuation task)
+- **Files modified:** 1
+
+## Accomplishments
+
+- Documented container ID format: `{server_hash}:{container_hash}` (two 64-char SHA256 hashes joined by colon)
+- Verified network access pattern: myunraid.net cloud relay URL is the working solution (direct LAN IP fails)
+- Corrected schema documentation: `isUpdateAvailable` does not exist, `state` is UPPERCASE, `names` prefixed with `/`
+- Documented n8n container configuration: UNRAID_HOST and UNRAID_API_KEY environment variables required
+- Updated authentication pattern: environment variables instead of n8n Header Auth credentials (more reliable)
+- Replaced all TBD placeholders in ARCHITECTURE.md with production-verified information
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Document Unraid GraphQL API contract in ARCHITECTURE.md** - `1670e10` (docs) - *Completed in Plan 14-01*
+2. **Task 2: Verify Unraid API connectivity end-to-end** - `d259b39` (docs)
+
+## Files Created/Modified
+
+- `ARCHITECTURE.md` - Added complete Unraid GraphQL API section with:
+  - Container ID format specification (no longer TBD)
+  - Network access findings (myunraid.net cloud relay)
+  - Authentication pattern (environment variables)
+  - n8n container configuration requirements
+  - Container query with actual response structure
+  - Schema corrections (state/names/isUpdateAvailable)
+
+## Decisions Made
+
+**1. Use myunraid.net cloud relay URL instead of direct LAN IP**
+- **Rationale:** Direct HTTP (http://192.168.90.103) causes nginx redirect to HTTPS, which strips auth headers on redirect. Direct HTTPS (https://192.168.90.103:8443) does not have /graphql endpoint. The myunraid.net cloud relay URL properly handles GraphQL endpoint routing and preserves auth headers.
+- **Impact:** Requires UNRAID_HOST to be set to myunraid.net URL format. The `host.docker.internal` approach documented in Plan 14-01 research did not work in production.
+
+**2. Environment variables instead of n8n Header Auth credentials**
+- **Rationale:** n8n Header Auth credential system was unreliable for GraphQL queries during testing. Direct environment variable reference in HTTP Request node header provides stable, testable configuration.
+- **Impact:** n8n container requires UNRAID_HOST and UNRAID_API_KEY environment variables. HTTP Request node uses `genericCredentialType: "none"` and manual header with `$env.UNRAID_API_KEY`.
+
+**3. Document schema discrepancies between research and actual API**
+- **Rationale:** Phase 14 research incorrectly documented `isUpdateAvailable` field on DockerContainer type. Actual production testing revealed this field does not exist in Unraid 7.2 schema.
+- **Impact:** Phase 15 will need to discover correct field for update status tracking via schema introspection. Documentation now clearly states schema differences from research.
+
+## Deviations from Plan
+
+None - plan executed exactly as written. User verification checkpoint resolved with comprehensive findings, all of which were documented in ARCHITECTURE.md as specified by the plan.
+
+## Issues Encountered
+
+None - verification checkpoint provided clear, complete information that was directly integrated into ARCHITECTURE.md.
+
+## User Setup Required
+
+**From Plan 14-01 (still applies):**
+1. Create Unraid API key with DOCKER:UPDATE_ANY permission
+2. Set UNRAID_HOST environment variable on n8n container (myunraid.net URL format)
+3. Set UNRAID_API_KEY environment variable on n8n container
+4. Update HTTP Request node configuration (genericCredentialType: none, allowUnauthorizedCerts: true)
+
+**Note:** The credential creation approach changed from n8n Header Auth to environment variables, but the API key creation step itself remains the same.
+
+## Next Phase Readiness
+
+**Phase 14 Complete:**
+- All INFRA requirements validated (INFRA-01: connectivity, INFRA-02: authentication, INFRA-03: container ID format)
+- Container ID format documented and ready for Phase 15 mutation usage
+- Network access pattern verified and documented
+- Schema corrections provide accurate baseline for Phase 15 development
+
+**Phase 15 Blockers:**
+- None - all prerequisites met
+- Phase 15 will need to discover correct update status field (isUpdateAvailable does not exist)
+
+**Key Artifacts for Phase 15:**
+- ARCHITECTURE.md Unraid GraphQL API section (complete contract documentation)
+- Container ID format: `{server_hash}:{container_hash}`
+- Working query: `query { docker { containers { id names state } } }`
+
+## Self-Check: PASSED
+
+**Modified files verification:**
+```bash
+✓ ARCHITECTURE.md exists
+✓ Container ID format documented (server_hash:container_hash)
+✓ myunraid.net cloud relay documentation present
+```
+
+**Commits verification:**
+```bash
+✓ 1670e10: Task 1 commit (from Plan 14-01)
+✓ d259b39: Task 2 commit (document connectivity findings)
+```
+
+All artifacts documented in SUMMARY.md exist and contain expected content.
+
+---
+*Phase: 14-unraid-api-access*
+*Completed: 2026-02-08*