Lucas Berger
ff289677ab
Target features: - n8n API for Claude Code (programmatic workflow access) - Telegram inline keyboard buttons - Batch container updates - Docker socket security - Environment variable audit - Unraid update sync Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
3.9 KiB
Unraid Docker Manager
What This Is
A Telegram bot that lets you manage Docker containers on your Unraid server. Control containers from your phone without needing to open a laptop — check status, view logs, start/stop/restart/update containers via simple keyword commands.
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
- 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
Active
Milestone v1.1: n8n Integration & Polish
- n8n API access for Claude Code (programmatic workflow read/update/test/logs)
- Telegram inline keyboard buttons (work around n8n native node issues)
- Batch container updates (verify/fix multi-container update)
- Docker socket security (remove direct socket from internet-exposed n8n)
- Environment variable audit (verify TELEGRAM_USERID/BOT_TOKEN necessity)
- Unraid update sync (clear "update available" when bot updates container)
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.0 (2026-02-02) Tech stack: n8n workflow + Telegram Bot API + Docker socket Files: n8n-workflow.json (~3,200 lines), README.md
Context
Environment:
- Unraid server with Intel N100 CPU, 32GB RAM
- n8n container with Docker socket access
- Multiple Docker containers (Plex, Sonarr, lldap, etc.)
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
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 text | ✓ Good |
| Text menu over keyboard | Native Telegram node replyKeyboard had issues | ✓ Good |
Current Milestone: v1.1 n8n Integration & Polish
Goal: Enable faster development iteration via n8n API access, revisit UX improvements (buttons), and harden security (remove direct Docker socket exposure).
Target features:
- n8n API for Claude Code — programmatic workflow access
- Telegram inline keyboard buttons — better UX than text menus
- Batch container updates — update multiple at once
- Docker socket security — remove direct exposure
- Environment variable audit — verify what's needed
- Unraid update sync — clear notifications properly
Last updated: 2026-02-02 after starting v1.1 milestone