unraid-docker-manager/.planning/milestones/v1.3-ROADMAP.md

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:

• 14-01-PLAN.md — Credential infrastructure and Unraid GraphQL test workflow nodes
• 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