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>
This commit is contained in:
Lucas Berger
2026-02-09 07:47:31 -05:00
parent ff0773b84b
commit 903e73d616
14 changed files with 1018 additions and 205 deletions
+52
View File
@@ -124,6 +124,58 @@ POST /api/v1/workflows/{id}/activate — Activate workflow
POST /api/v1/workflows/{id}/deactivate — Deactivate workflow
```
## Unraid API Access
Credentials use dual storage:
- `.env.unraid-api` (gitignored) for CLI testing — contains `UNRAID_HOST` and `UNRAID_API_KEY`
- n8n Header Auth credential "Unraid API Key" for workflow nodes
**IMPORTANT: Each Bash tool call is a fresh shell.** You must source the env file in the SAME command chain as the curl call.
### Loading credentials (CLI)
```bash
. .env.unraid-api; curl -X POST "${UNRAID_HOST}/graphql" \
-H "Content-Type: application/json" \
-H "x-api-key: ${UNRAID_API_KEY}" \
-d '{"query": "query { docker { containers { id names state } } }"}'
```
### n8n workflow nodes
- **Authentication:** n8n Header Auth credential (not environment variables)
- **URL:** `={{ $env.UNRAID_HOST }}/graphql` — reads host from n8n container env var
- **Credential:** "Unraid API Key" Header Auth — sends `x-api-key` header automatically
### n8n container setup
**Required environment variable:**
- `UNRAID_HOST` — Unraid myunraid.net URL (without /graphql suffix)
- Format: `https://{ip-dashed}.{hash}.myunraid.net:8443`
**Required n8n credential:**
- Type: Header Auth, Name: "Unraid API Key", Header: `x-api-key`, Value: API key
**Why myunraid.net URL:** Direct LAN IP fails because Unraid's nginx redirects HTTP→HTTPS, stripping auth headers on redirect. The myunraid.net cloud relay URL avoids this issue and provides valid SSL certs.
### API key creation
Create via Unraid WebGUI or SSH:
**WebGUI:** Settings -> Management Access -> API Keys -> Create
- Name: "Docker Manager Bot"
- Permissions: `DOCKER:UPDATE_ANY`
- Description: "Container update status sync"
**SSH:**
```bash
unraid-api apikey --create \
--name "Docker Manager Bot" \
--permissions "DOCKER:UPDATE_ANY" \
--description "Container update status sync" \
--json
```
## Project Structure
- `n8n-workflow.json` — Main n8n workflow (Telegram bot entry point)