Lucas Berger
63df54e8e3
12 requirements across 3 phases: - Phase 10: Modularization, update all, callback limits (7 reqs) - Phase 11: Unraid sync, env audit, tech debt (4 reqs) - Phase 12: Documentation overhaul (1 req) Removed WEB-01 (webhook fix) - already resolved. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
110 lines
5.2 KiB
Markdown
110 lines
5.2 KiB
Markdown
# Unraid Docker Manager
|
|
|
|
## What This Is
|
|
|
|
A Telegram bot that lets you manage Docker containers on your Unraid server via inline keyboard buttons and text commands. Control containers from your phone without needing to open a laptop — check status, view logs, start/stop/restart/update containers, batch operations on multiple containers at once.
|
|
|
|
## Core Value
|
|
|
|
When you get a container update notification or notice a service is down, you can immediately investigate and act from your phone.
|
|
|
|
## Requirements
|
|
|
|
### Validated
|
|
|
|
**v1.0:**
|
|
- ✓ Send a message to the bot and receive a response — v1.0
|
|
- ✓ Check container status ("status") — v1.0
|
|
- ✓ Start a container by name — v1.0
|
|
- ✓ Stop a container by name — v1.0
|
|
- ✓ Restart a container by name — v1.0
|
|
- ✓ Update a container (pull new image, recreate) — v1.0
|
|
- ✓ View container logs with configurable line count — v1.0
|
|
- ✓ Bot only responds to your Telegram user ID — v1.0
|
|
|
|
**v1.1:**
|
|
- ✓ n8n API access for Claude Code (programmatic workflow read/update/test/logs) — v1.1
|
|
- ✓ Docker socket security (remove direct socket from internet-exposed n8n) — v1.1
|
|
- ✓ Telegram inline keyboard buttons (container list with pagination and action buttons) — v1.1
|
|
- ✓ Batch container operations (update/start/stop/restart multiple at once) — v1.1
|
|
- ✓ Confirmation dialogs for dangerous actions (stop, update) — v1.1
|
|
- ✓ Progress feedback during operations (message edits) — v1.1
|
|
|
|
### Active
|
|
|
|
**Milestone v1.2: Modularization & Polish**
|
|
|
|
- [ ] Workflow modularization (break main workflow into sub-workflows)
|
|
- [ ] Update all containers via text command and inline keyboard
|
|
- [ ] Fix callback data limits (batch selection >2 containers, long names)
|
|
- [ ] Unraid update sync (clear "update available" when bot updates container)
|
|
- [ ] Environment variable audit (verify TELEGRAM_USERID/BOT_TOKEN necessity)
|
|
- [ ] Documentation update (proxy architecture, new features)
|
|
|
|
### Out of Scope
|
|
|
|
- Taking over Unraid notifications — keep existing notification system, this bot is for control
|
|
- Deploying new containers — manage existing only, not create new ones
|
|
- Natural language understanding — simple keyword matching sufficient, Claude API adds complexity
|
|
- Proactive monitoring/notifications — bot is reactive (you ask, it answers)
|
|
- Resource queries — "what's using the most memory?" deferred to future version
|
|
|
|
## Current State
|
|
|
|
**Shipped:** v1.1 (2026-02-04)
|
|
**Tech stack:** n8n workflow + Telegram Bot API + Docker socket proxy
|
|
**Files:** n8n-workflow.json (~8,500 lines), README.md
|
|
**Architecture:** tecnativa/docker-socket-proxy filters Docker API access
|
|
|
|
## Context
|
|
|
|
**Environment:**
|
|
- Unraid server with Intel N100 CPU, 32GB RAM
|
|
- n8n container with Docker socket proxy access (no direct socket mount)
|
|
- Multiple Docker containers (Plex, Sonarr, lldap, etc.)
|
|
- docker-socket-proxy on dockernet network
|
|
|
|
**Constraints:**
|
|
- Platform: Unraid (Docker-based)
|
|
- Orchestration: n8n (already running)
|
|
- Matching: Keyword/substring with exact-match priority
|
|
- Auth: Single user via Telegram ID
|
|
- Logs: Configurable line count, default 50, max 1000
|
|
- Callback data: 64-byte Telegram limit (affects batch/selection features)
|
|
|
|
## Key Decisions
|
|
|
|
| Decision | Rationale | Outcome |
|
|
|----------|-----------|---------|
|
|
| Use keyword matching over NLU | Simple substring matching works well, Claude API adds complexity | ✓ Good |
|
|
| Use n8n for orchestration | Already running, handles Telegram webhooks | ✓ Good |
|
|
| Manage existing containers only | Keeps scope focused, deployment rarely needed from mobile | ✓ Good |
|
|
| Single user auth via Telegram ID | Simple security, only one person needs access | ✓ Good |
|
|
| Static curl binary mount | Hardened n8n image lacks package manager | ✓ Good |
|
|
| 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 |
|
|
| 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 |
|
|
| 30-second confirmation timeout | Prevents stale confirmations | ✓ Good |
|
|
| Batch stop requires confirmation | Fuzzy matching risk for destructive operations | ✓ Good |
|
|
| Two-phase batch execution | Callbacks have names but no IDs - need lookup | ✓ Good |
|
|
| Update all filters to :latest | Performance optimization - full check would be slow | ✓ Good |
|
|
|
|
## Current Milestone: v1.2 Modularization & Polish
|
|
|
|
**Goal:** Modularize workflow for maintainability, add "update all" functionality, fix callback limits, and polish remaining issues.
|
|
|
|
**Target features:**
|
|
- Workflow modularization into sub-workflows
|
|
- "Update all" command (text and inline keyboard)
|
|
- Callback data limit fix (batch selection, long names)
|
|
- Unraid badge sync (UNR-01)
|
|
- Environment audit (ENV-01, ENV-02)
|
|
- Documentation overhaul (proxy architecture)
|
|
|
|
---
|
|
*Last updated: 2026-02-04 after v1.1 milestone*
|