unraid-docker-manager/.planning/phases/14-unraid-api-access/14-01-SUMMARY.md

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

phase	plan	subsystem	tags	dependency-graph	tech-stack	key-files	decisions	metrics
14-unraid-api-access	01	infrastructure	credentials graphql testing n8n	requires provides affects n8n-api-credentials telegram-bot unraid-api-credentials unraid-graphql-test unraid-connectivity-validation main-workflow deployment	added patterns unraid-graphql-api dual-credential-storage graphql-error-handling telegram-response-formatting	created modified .env.unraid-api .gitignore CLAUDE.md n8n-workflow.json	what why alternatives chosen Dual credential storage pattern Mirror existing .env.n8n-api pattern for consistency, CLI testability n8n-only-credential single-unified-env-file dual-storage what why alternatives chosen Error handling approach Clear, actionable feedback with specific troubleshooting steps generic-errors error-codes-only descriptive-messages what why alternatives chosen Placeholder credential ID Credential must be created manually in n8n UI by user auto-create-credential hardcode-test-id placeholder-with-docs	duration completed tasks files_changed commits 3 minutes 2026-02-09T01:28:46Z 2 3 2

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:

1. Create Unraid API key (DOCKER:UPDATE_ANY permission)
2. Populate .env.unraid-api with actual credentials
3. Create "Unraid API Key" Header Auth credential in n8n UI
4. Update HTTP Request node's credential ID (currently placeholder)
5. 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:

1. HTTP errors (continueOnFail): Network issues, auth failures, SSL problems
2. GraphQL errors: Query syntax, permission issues, API version incompatibility
3. 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:

1. Populate .env.unraid-api with real credentials
2. Create n8n Header Auth credential "Unraid API Key"
3. Update HTTP Request node credential ID in n8n UI
4. Send "unraid" to Telegram bot
5. 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.