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

9.2 KiB

Raw Permalink Blame History

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

phase

plan

subsystem

Phase 14 Plan 01: Unraid API Access Foundation

One-liner: Credential infrastructure and GraphQL test nodes for Unraid API connectivity validation with descriptive error handling

Summary

Established the foundation for Unraid GraphQL API integration by creating credential storage infrastructure (.env.unraid-api) mirroring the existing n8n API pattern, and building workflow nodes that query the Unraid GraphQL API to validate connectivity, authentication, and container data structure. The implementation includes comprehensive error handling with clear, actionable feedback for common failure scenarios (network unreachable, invalid credentials, API version mismatch).

Key capabilities added:

Credential template file (.env.unraid-api) with UNRAID_HOST and UNRAID_API_KEY
Complete documentation in CLAUDE.md for API access patterns, credential creation, and networking setup
"unraid" test command in Telegram bot (auth-protected)
Unraid GraphQL query nodes with validation and error handling
Test query for critical fields: id, names, state, isUpdateAvailable

User setup required:

Create Unraid API key (DOCKER:UPDATE_ANY permission)
Populate .env.unraid-api with actual credentials
Create "Unraid API Key" Header Auth credential in n8n UI
Update HTTP Request node's credential ID (currently placeholder)
If using host.docker.internal, add --add-host flag to n8n container

Tasks Completed

Task 1: Create credential infrastructure

Status: Complete (commit 9cacfd9)

What was built:

Created .env.unraid-api template file with UNRAID_HOST and UNRAID_API_KEY variables
Added .env.unraid-api to .gitignore (properly excluded from version control)
Added comprehensive "Unraid API Access" section to CLAUDE.md documenting:
- Credential loading pattern (source in same command chain)
- GraphQL query pattern with example
- API key creation steps (WebGUI and SSH methods)
- n8n container networking setup (host.docker.internal)

Files modified:

.env.unraid-api (created)
.gitignore (added entry)
CLAUDE.md (added 57 lines of documentation)

Verification:

.env.unraid-api exists and is properly gitignored (not in git status)
CLAUDE.md contains "Unraid API Access" section with all required docs
Pattern mirrors existing .env.n8n-api infrastructure exactly

Task 2: Add Unraid GraphQL test nodes to main workflow

Status: Complete (commit 1314338)

What was built:

Added "unraid" keyword rule to Keyword Router Switch node (contains match, case-insensitive)
Created HTTP Request node "Unraid API Test":
- POST to UNRAID_HOST/graphql
- Header Auth with placeholder credential
- Query: docker.containers (id, names, state, isUpdateAvailable)
- ignoreSSLIssues: true (handles self-signed certs)
- continueOnFail: true (allows Code node to handle errors gracefully)
Created Code node "Validate Unraid Response":
- HTTP error handling (network, auth failures)
- GraphQL error handling (query errors, API version issues)
- Response structure validation (data.docker.containers exists)
- Success response with container count, update count, sample data
- All error paths provide clear troubleshooting guidance
Created Telegram Send node "Send Unraid Test Result":
- Uses existing Telegram credential (I0xTTiASl7C1NZhJ)
- HTML parse mode for formatted output
- Sends validation result back to user

Files modified:

n8n-workflow.json (169 nodes total, +3 new)

Wiring:

Keyword Router output[9] -> Unraid API Test
Unraid API Test -> Validate Unraid Response
Validate Unraid Response -> Send Unraid Test Result

Verification:

All 3 nodes present in workflow JSON
"unraid" rule added to Keyword Router (10 total rules)
Connections properly wired (verified in workflow.connections)
Workflow pushed to n8n successfully (HTTP 200)
Goes through existing Auth IF node (auth-protected like all text commands)

Deviations from Plan

None - plan executed exactly as written.

Key Decisions Made

1. Dual credential storage pattern

Decision: Store credentials in both .env.unraid-api and n8n Header Auth credential
Rationale: Mirrors existing .env.n8n-api pattern for consistency, enables CLI testing and deploy scripts while allowing workflow nodes to use n8n's credential management
Impact: Credential setup requires two steps (create file + create n8n credential), but provides flexibility and consistency

2. Descriptive error handling

Decision: Provide detailed error messages with specific troubleshooting steps
Rationale: Common failure modes (network unreachable, invalid key, API version mismatch) benefit from immediate context rather than forcing users to check logs
Impact: Larger Code node, but significantly better user experience during setup

3. Placeholder credential approach

Decision: Use placeholder credential ID with manual n8n UI setup
Rationale: n8n API doesn't support credential creation, and hardcoding test credentials would be security risk
Impact: Requires manual credential creation step documented in plan frontmatter user_setup section

Technical Notes

GraphQL Query Structure:

{
  "query": "query { docker { containers { id names state isUpdateAvailable } } }"
}

Fields requested are the minimum required by downstream phases (Phase 15 update sync logic needs container ID matching, state tracking, and update availability status).

Error Handling Patterns:

HTTP errors (continueOnFail): Network issues, auth failures, SSL problems
GraphQL errors: Query syntax, permission issues, API version incompatibility
Structure validation: Ensures response has expected data.docker.containers shape

n8n Workflow Conventions Applied:

Data chain pattern: $('Telegram Trigger').item.json.message.chat.id for cross-node references
Dynamic input: $input.item.json for Code node (successor of HTTP Request)
Credential references: Existing Telegram credential ID used, placeholder for Unraid credential

Testing Notes

Manual test after user setup:

Populate .env.unraid-api with real credentials
Create n8n Header Auth credential "Unraid API Key"
Update HTTP Request node credential ID in n8n UI
Send "unraid" to Telegram bot
Expect: Success message with container count, update count, sample container list

Expected success output format:

✅ Unraid API Connected

Containers: 25
Updates available: 3
ID format: abc123def456

Sample:
• plex (running) 🔄
• nginx (running)
• postgres (running)
...

Common error scenarios handled:

Network unreachable: "Can n8n reach the Unraid host? (--add-host flag)"
Invalid API key: "Is the API key valid?"
Wrong host: "Is UNRAID_HOST correct?"
Old Unraid version: "Is Unraid GraphQL API enabled? (v7.2+ or Connect plugin)"

Next Steps

Immediate (Phase 14 Plan 02):

User completes credential setup (API key creation, n8n credential)
Test "unraid" command to validate connectivity
Document actual Unraid version and GraphQL API availability

Future (Phase 15+):

Extend query to include additional fields (timestamps, registry info)
Add container matching logic (Unraid ID <-> Docker ID mapping)
Implement update status sync (mark Unraid container as updated after bot update)
Handle edge cases (multi-repository containers, custom tags)

Self-Check: PASSED

Created files verification:

✓ .env.unraid-api exists (gitignored, not in version control)
✓ .gitignore entry present
✓ CLAUDE.md documentation added

Modified files verification:

✓ n8n-workflow.json contains all 3 new nodes
✓ Keyword Router has "unraid" rule (total 10 rules)
✓ Connections properly wired (Router -> HTTP -> Code -> Telegram)

Commits verification:

✓ 9cacfd9: chore(14-01): create Unraid API credential infrastructure
✓ 1314338: feat(14-01): add Unraid GraphQL test nodes to main workflow

Deployment verification:

✓ Workflow pushed to n8n (HTTP 200)
✓ Main workflow ID: HmiXBlJefBRPMS0m4iNYc

All artifacts exist, all commits present, workflow deployed successfully.

9.2 KiB Raw Permalink Blame History