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
+22
-21
@@ -2,7 +2,7 @@
|
||||
|
||||
## What This Is
|
||||
|
||||
A Telegram bot that lets you manage Docker containers on your Unraid server via inline keyboard buttons and text commands. Built on a modular n8n sub-workflow architecture with 7 domain-specific sub-workflows. Control containers from your phone — check status, view logs, start/stop/restart/update containers, batch operations, and update all :latest containers at once.
|
||||
A Telegram bot that lets you manage Docker containers on your Unraid server via inline keyboard buttons and text commands. Built on a modular n8n sub-workflow architecture with 7 domain-specific sub-workflows. Control containers from your phone — check status, view logs, start/stop/restart/update containers, batch operations, and update all :latest containers at once. Includes Unraid GraphQL API connectivity for native Unraid integration.
|
||||
|
||||
## Core Value
|
||||
|
||||
@@ -44,12 +44,18 @@ When you get a container update notification or notice a service is down, you ca
|
||||
- ✓ Update flow consolidated (no duplicate logic) — v1.2
|
||||
- ✓ Correlation ID tracking across sub-workflow boundaries — v1.2
|
||||
|
||||
**v1.3:**
|
||||
- ✓ n8n container can reach Unraid GraphQL API endpoint — v1.3
|
||||
- ✓ Unraid API key with Docker update permission, stored securely — v1.3
|
||||
- ✓ Container ID format verified and documented — v1.3
|
||||
|
||||
### Active
|
||||
|
||||
**v1.3: Unraid Update Status Sync**
|
||||
- [ ] After bot updates a container, Unraid recognizes it as current (no stale badges)
|
||||
- [ ] No false-positive Unraid Telegram notifications for containers already updated via bot
|
||||
- [ ] No manual Unraid login required to clear update status after bot updates
|
||||
**v1.4: Unraid API Native (planned)**
|
||||
- [ ] Replace Docker socket proxy with Unraid GraphQL API for all container operations
|
||||
- [ ] Remove docker-socket-proxy container dependency
|
||||
- [ ] Container updates via Unraid API (naturally resolves badge sync problem)
|
||||
- [ ] Documentation covers full Unraid API setup and migration
|
||||
|
||||
### Out of Scope
|
||||
|
||||
@@ -62,10 +68,10 @@ When you get a container update notification or notice a service is down, you ca
|
||||
|
||||
## Current State
|
||||
|
||||
**Shipped:** v1.2 (2026-02-08)
|
||||
**Tech stack:** n8n workflow + Telegram Bot API + Docker socket proxy
|
||||
**Architecture:** 1 main workflow (166 nodes) + 7 sub-workflows (121 nodes) = 287 total nodes
|
||||
**Files:** 8 workflow JSON files (10,987 LOC), README.md (264 lines), ARCHITECTURE.md (725 lines)
|
||||
**Shipped:** v1.3 (2026-02-09)
|
||||
**Tech stack:** n8n workflow + Telegram Bot API + Docker socket proxy + Unraid GraphQL API
|
||||
**Architecture:** 1 main workflow (169 nodes) + 7 sub-workflows (121 nodes) = 290 total nodes
|
||||
**Files:** 8 workflow JSON files (~11K LOC), README.md, ARCHITECTURE.md
|
||||
**Sub-workflows:** Update, Actions, Logs, Batch UI, Status, Confirmation, Matching
|
||||
|
||||
## Context
|
||||
@@ -75,6 +81,7 @@ When you get a container update notification or notice a service is down, you ca
|
||||
- n8n container with Docker socket proxy access (no direct socket mount)
|
||||
- Multiple Docker containers (Plex, Sonarr, lldap, etc.)
|
||||
- docker-socket-proxy on dockernet network
|
||||
- Unraid GraphQL API accessible via myunraid.net cloud relay
|
||||
|
||||
**Constraints:**
|
||||
- Platform: Unraid (Docker-based)
|
||||
@@ -84,6 +91,7 @@ When you get a container update notification or notice a service is down, you ca
|
||||
- Logs: Configurable line count, default 50, max 1000
|
||||
- Callback data: Bitmap encoding overcomes 64-byte Telegram limit
|
||||
- n8n static data: Execution-scoped only (no persistent cross-execution state)
|
||||
- Unraid API: myunraid.net cloud relay required (direct LAN IP fails due to nginx redirect)
|
||||
|
||||
**Known tech debt:**
|
||||
- 3 orphan nodes in main workflow (legacy dead code, unreachable)
|
||||
@@ -102,7 +110,7 @@ When you get a container update notification or notice a service is down, you ca
|
||||
| Exact match priority | Prevents substring collisions (plex vs jellyplex) | ✓ Good |
|
||||
| Default to :latest tag | Prevents Docker API from pulling all tags | ✓ Good |
|
||||
| HTML escape logs | Log content may contain <tag> text | ✓ Good |
|
||||
| docker-socket-proxy for security | Filters dangerous APIs (exec, build, commit) at network level | ✓ Good |
|
||||
| docker-socket-proxy for security | Filters dangerous APIs (exec, build, commit) at network level | ⚠️ Revisit (replacing with Unraid API in v1.4) |
|
||||
| Container create API allowed | Update command needs container recreation | ✓ Good |
|
||||
| Colon callback format | Compact format fits 64-byte limit | ✓ Good |
|
||||
| editMessageText transitions | Clean UX with no message clutter | ✓ Good |
|
||||
@@ -115,16 +123,9 @@ When you get a container update notification or notice a service is down, you ca
|
||||
| Action-based sub-workflow routing | Sub-workflow returns action field, main routes to Telegram handlers | ✓ Good |
|
||||
| Correlation IDs without persistent logging | Timestamp+random string traces requests; ring buffer non-viable on n8n | ✓ Good |
|
||||
| Infrastructure container exclusion | Exclude n8n and socket-proxy from "update all" to prevent self-destruction | ✓ Good |
|
||||
| Document Unraid badge as limitation | Unraid API integration adds complexity for cosmetic issue | ⚠️ Revisit |
|
||||
|
||||
## Current Milestone: v1.3 Unraid Update Status Sync
|
||||
|
||||
**Goal:** After the bot updates a container, Unraid recognizes it's current — no stale badges, no false-positive notifications.
|
||||
|
||||
**Target features:**
|
||||
- Sync update status back to Unraid after bot-initiated container updates
|
||||
- Eliminate false-positive Unraid Telegram notifications for already-updated containers
|
||||
- (Nice-to-have) Use Unraid's update detection data in the bot's update flow
|
||||
| myunraid.net cloud relay for Unraid API | Direct LAN IP fails (nginx strips auth headers on redirect) | ✓ Good |
|
||||
| Environment variables for Unraid API auth | More reliable than n8n Header Auth credential system for GraphQL | ✓ Good |
|
||||
| Descope v1.3 to Phase 14 only | Phases 15-16 superseded by v1.4 Unraid API Native approach | ✓ Good |
|
||||
|
||||
---
|
||||
*Last updated: 2026-02-08 after v1.3 milestone started*
|
||||
*Last updated: 2026-02-09 after v1.3 milestone shipped*
|
||||
|
||||
Reference in New Issue
Block a user