Files

T

Lucas Berger 903e73d616 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

6.5 KiB

Raw Permalink Blame History

phase, plan, subsystem, tags, dependency-graph, tech-stack, key-files, key-decisions, metrics

phase

plan

subsystem

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:

Task 1: Document Unraid GraphQL API contract in ARCHITECTURE.md - 1670e10 (docs) - Completed in Plan 14-01
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):

Create Unraid API key with DOCKER:UPDATE_ANY permission
Set UNRAID_HOST environment variable on n8n container (myunraid.net URL format)
Set UNRAID_API_KEY environment variable on n8n container
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:

✓ ARCHITECTURE.md exists
✓ Container ID format documented (server_hash:container_hash)
✓ myunraid.net cloud relay documentation present

Commits verification:

✓ 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

6.5 KiB Raw Permalink Blame History