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

Requirements: Unraid Docker Manager

Defined: 2026-02-04 Core Value: When you get a container update notification or notice a service is down, you can immediately investigate and act from your phone.

v1.0 Requirements (Validated)

Core Commands

• ✓ CMD-01: User can send a message to the bot and receive a response — v1.0
• ✓ CMD-02: User can check container status via "status" command — v1.0
• ✓ CMD-03: User can start a container by name — v1.0
• ✓ CMD-04: User can stop a container by name — v1.0
• ✓ CMD-05: User can restart a container by name — v1.0
• ✓ CMD-06: User can update a container (pull new image, recreate) — v1.0
• ✓ CMD-07: User can view container logs with configurable line count — v1.0

Security

• ✓ SEC-01: Bot only responds to configured Telegram user ID — v1.0

v1.1 Requirements (Validated)

n8n API

• ✓ API-01: n8n API access for programmatic workflow management — v1.1

Docker Security

• ✓ SEC-02: Docker socket access via filtered proxy (no direct socket mount) — v1.1

Inline Keyboard UX

• ✓ UX-01: Container list with pagination via inline keyboard — v1.1
• ✓ UX-02: Action buttons for container operations — v1.1
• ✓ UX-03: Confirmation dialogs for dangerous actions (stop, update) — v1.1
• ✓ UX-04: Progress feedback via message edits during operations — v1.1

Batch Operations

• ✓ BATCH-01: Batch start multiple containers at once — v1.1
• ✓ BATCH-02: Batch stop multiple containers at once — v1.1
• ✓ BATCH-03: Batch restart multiple containers at once — v1.1

v1.2 Requirements (Active)

Modularization

• ✓ MOD-01: Main workflow broken into logical sub-workflows for maintainability — Phase 10/10.1
• ✓ MOD-02: Sub-workflows callable from main workflow without duplication — Phase 10/10.1

Batch Updates

• ✓ BATCH-04: User can update all containers with :latest tag via text command ("update all") — Phase 11/12
• ✓ BATCH-05: User can update all containers with :latest tag via inline keyboard — Phase 11/12
• ✓ BATCH-06: Batch selection keyboard supports selecting more than 2 containers — Phase 11
• ✓ BATCH-07: Batch selection keyboard supports containers with long names — Phase 11

Unraid Integration

• ✓ UNR-01: After bot updates a container, Unraid UI no longer shows "update available" for that container — Documented as known limitation with workaround, Phase 12

Environment & Config

• ✓ ENV-01: Documentation clarifies TELEGRAM_USERID env var necessity (required vs hardcoded) — Phase 12
• ✓ ENV-02: Documentation clarifies TELEGRAM_BOT_TOKEN env var necessity (env var vs n8n credential) — Phase 12

Technical Debt

• ✓ DEBT-01: README documents proxy architecture (not direct docker.sock mounting) — Phase 12
• ✓ DEBT-02: Fix duplicate --max-time flags in image pull command — Verified fixed (single --max-time 600, no duplicates), Phase 12
• ✓ DEBT-03: Consolidate duplicated update flow between single and batch paths — Phase 10

v2+ Requirements (Deferred)

Resource Monitoring

• RES-01: User can query resource usage ("what's using the most memory?")

Notifications

• NOTF-01: Bot proactively notifies when containers have updates available

Out of Scope

Feature	Reason
Take over Unraid notifications	Keep existing notification system, bot is for control
Deploy new containers	Manage existing only, not create new ones
Natural language understanding	Simple keyword matching sufficient, Claude API adds complexity
Proactive monitoring	Bot is reactive (you ask, it answers)
Mobile app	Telegram is the interface

Traceability

Requirement	Phase	Status
MOD-01	Phase 10/10.1	Complete
MOD-02	Phase 10/10.1	Complete
DEBT-03	Phase 10	Complete
BATCH-04	Phase 11/12	Complete
BATCH-05	Phase 11/12	Complete
BATCH-06	Phase 11	Complete
BATCH-07	Phase 11	Complete
UNR-01	Phase 12	Complete
ENV-01	Phase 12	Complete
ENV-02	Phase 12	Complete
DEBT-02	Phase 12	Complete
DEBT-01	Phase 12	Complete

Coverage:

• v1.2 requirements: 12 total
• Mapped to phases: 12
• Unmapped: 0 ✓

---

Requirements defined: 2026-02-04 Last updated: 2026-02-04 after v1.2 milestone initialization