Lucas Berger
65 lines
2.6 KiB
Markdown
65 lines
2.6 KiB
Markdown
# Phase 14: Unraid API Access - Context
|
|
|
|
**Gathered:** 2026-02-08
|
|
**Status:** Ready for planning
|
|
|
|
<domain>
|
|
## Phase Boundary
|
|
|
|
Validate GraphQL API connectivity and establish secure authentication from n8n container to Unraid host. Includes credential storage, network connectivity verification, test query execution, and container ID format documentation. Does NOT include mutation calls (Phase 15) or batch operations (Phase 16).
|
|
|
|
</domain>
|
|
|
|
<decisions>
|
|
## Implementation Decisions
|
|
|
|
### Credential management
|
|
- Dual storage: `.env.unraid-api` file (for CLI/deploy scripts) + n8n credential (for workflow nodes)
|
|
- `.env.unraid-api` contains both `UNRAID_API_KEY` and `UNRAID_HOST` (mirrors `.env.n8n-api` pattern)
|
|
- Phase includes documentation for creating the Unraid API key in WebGUI with correct permissions
|
|
- File is gitignored
|
|
|
|
### Network connectivity
|
|
- User runs Unraid on default WebGUI ports — GraphQL API assumed on same port
|
|
- HTTP vs HTTPS and self-signed cert handling needs to be figured out during research/testing
|
|
- Connectivity verification done purely through n8n workflow nodes — no separate test script
|
|
- Host URL stored in `UNRAID_HOST` env var — user configures during setup
|
|
|
|
### GraphQL query design
|
|
- Document only the queries/mutations relevant to update sync — not the full Docker schema
|
|
- Container ID format mapping needs research — we don't know how Unraid identifies containers in GraphQL yet
|
|
- GraphQL API contract documented in ARCHITECTURE.md alongside existing Docker API contract
|
|
|
|
### Error handling & feedback
|
|
- Clear, descriptive error messages on failure (what failed, why, what to check)
|
|
- Use existing error logging system — same pattern as Docker API errors, not a separate log category
|
|
- Phase 14 tests connectivity only — permission validation happens naturally in Phase 15 when mutations are attempted
|
|
- No user-facing Telegram health check command for Unraid API — errors surface naturally during sync failures
|
|
|
|
### Claude's Discretion
|
|
- n8n credential type selection (based on Unraid GraphQL API's actual auth mechanism)
|
|
- Network approach for n8n container reaching Unraid host (host IP, Docker networking, etc.)
|
|
- What fields to include in the test query (based on what downstream phases need)
|
|
|
|
</decisions>
|
|
|
|
<specifics>
|
|
## Specific Ideas
|
|
|
|
- Mirror the `.env.n8n-api` pattern for credential file naming and structure
|
|
- Keep the ARCHITECTURE.md GraphQL section consistent with the existing Docker API documentation style
|
|
|
|
</specifics>
|
|
|
|
<deferred>
|
|
## Deferred Ideas
|
|
|
|
None — discussion stayed within phase scope
|
|
|
|
</deferred>
|
|
|
|
---
|
|
|
|
*Phase: 14-unraid-api-access*
|
|
*Context gathered: 2026-02-08*
|