unraid-docker-manager/.planning/PROJECT.md

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