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:
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user