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>
This commit is contained in:
Lucas Berger
@@ -0,0 +1,59 @@
|
||||
# Requirements Archive: v1.3 Unraid Update Status Sync
|
||||
|
||||
**Archived:** 2026-02-09
|
||||
**Status:** SHIPPED (descoped — Phase 14 only)
|
||||
|
||||
---
|
||||
|
||||
## v1.3 Requirements
|
||||
|
||||
Requirements for Unraid Update Status Sync.
|
||||
|
||||
### Infrastructure
|
||||
|
||||
- [x] **INFRA-01**: n8n container can reach Unraid GraphQL API endpoint — *Validated (Phase 14)*
|
||||
- [x] **INFRA-02**: Unraid API key created with Docker update permission, stored securely — *Validated (Phase 14)*
|
||||
- [x] **INFRA-03**: Container ID format verified via GraphQL query (document actual format) — *Validated (Phase 14, format: {server_hash}:{container_hash})*
|
||||
|
||||
### Sync — SUPERSEDED
|
||||
|
||||
*Dropped: Superseded by v1.4 Unraid API Native. When Unraid's GraphQL API replaces the Docker socket proxy for all container operations, the badge sync problem is eliminated — Unraid already knows about updates it performs.*
|
||||
|
||||
- [ ] **SYNC-01**: After bot updates a single container (text command), Unraid badge clears automatically — *Superseded*
|
||||
- [ ] **SYNC-02**: After bot updates a single container (inline keyboard), Unraid badge clears automatically — *Superseded*
|
||||
- [ ] **SYNC-03**: After batch "update all" operation, all updated containers sync to Unraid in one call — *Superseded*
|
||||
- [ ] **SYNC-04**: After batch selection update, all selected containers sync to Unraid in one call — *Superseded*
|
||||
- [ ] **SYNC-05**: Sync failure does not block or fail the container update itself (best-effort) — *Superseded*
|
||||
- [ ] **SYNC-06**: User receives no false-positive Unraid update notifications for bot-updated containers — *Superseded*
|
||||
|
||||
### Documentation — DEFERRED
|
||||
|
||||
*Deferred to v1.4: Documentation will cover the full Unraid API Native migration rather than just sync.*
|
||||
|
||||
- [ ] **DOC-01**: README documents Unraid API setup (key creation, n8n container config) — *Deferred to v1.4*
|
||||
- [ ] **DOC-02**: ARCHITECTURE.md documents Unraid sync integration (GraphQL API, data flow, new nodes) — *Partial (API contract documented in Phase 14), full integration docs deferred to v1.4*
|
||||
|
||||
## Traceability
|
||||
|
||||
| Requirement | Phase | Final Status |
|
||||
|-------------|-------|--------------|
|
||||
| INFRA-01 | Phase 14 | Validated |
|
||||
| INFRA-02 | Phase 14 | Validated |
|
||||
| INFRA-03 | Phase 14 | Validated |
|
||||
| SYNC-01 | — | Superseded (v1.4) |
|
||||
| SYNC-02 | — | Superseded (v1.4) |
|
||||
| SYNC-03 | — | Superseded (v1.4) |
|
||||
| SYNC-04 | — | Superseded (v1.4) |
|
||||
| SYNC-05 | — | Superseded (v1.4) |
|
||||
| SYNC-06 | — | Superseded (v1.4) |
|
||||
| DOC-01 | — | Deferred (v1.4) |
|
||||
| DOC-02 | Phase 14 (partial) | Deferred (v1.4) |
|
||||
|
||||
**Summary:**
|
||||
- Validated: 3 (INFRA-01, INFRA-02, INFRA-03)
|
||||
- Superseded: 6 (SYNC-01 through SYNC-06)
|
||||
- Deferred: 2 (DOC-01, DOC-02)
|
||||
|
||||
---
|
||||
*Requirements defined: 2026-02-08*
|
||||
*Archived: 2026-02-09 — v1.3 shipped (descoped)*
|
||||
@@ -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_
|
||||
Reference in New Issue
Block a user