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

Project State — Unraid Docker Manager

Project Reference

See: .planning/PROJECT.md (updated 2026-02-02)

Core value: Immediate container control from your phone Current focus: v1.1 Phase 9 in progress — batch execution and progress complete

Current Position

• Milestone: v1.1 — n8n Integration & Polish
• Phase: 9 of 11 (Batch Operations)
• Plan: 3 of 3 complete
• Status: Phase complete
• Last activity: 2026-02-04 — Completed 09-03-PLAN.md (update all and inline multi-select)

Progress

v1.1: [████████░ ] 81%

Phase 6:  n8n API Access              [##########] Complete
Phase 7:  Socket Security             [##########] Complete (3/3)
Phase 8:  Inline Keyboard Infra       [##########] Complete (3/3)
Phase 9:  Batch Operations            [##########] Complete (3/3)
Phase 10: Polish & Audit              [          ] Pending
Phase 11: Documentation Overhaul      [          ] Pending

Accumulated Context

Key Decisions

Decision	Rationale	Phase
n8n API first	Enables faster iteration on all subsequent phases	6
n8n API key never expires	Development environment on private network, rotation not critical	06-01
.env.n8n-api filename	Specific purpose, won't conflict with future env files	06-01
docker-socket-proxy deployed via user action	Consistent with Unraid-native approach, user has direct GUI access	07-01
dockernet network for n8n and proxy	Custom bridge network provides DNS resolution between containers	07-01
Connectivity verified through network config	Docker DNS guarantees hostname resolution on same custom network	07-01
Container create API allowed despite security risk	Update command needs container recreation; workflow logic controls params	07-03
Verification via documented proxy behavior	Deployment environment constraints; tecnativa proxy behavior well-documented	07-03
Credential name "Telegram account"	Matches actual n8n credential; ID I0xTTiASl7C1NZhJ	07-02
docker.sock mount removed from n8n	All API calls now go through proxy; no direct socket access	07-02
Webhook issue deferred to Phase 10	WEB-01 added; bot works via manual execute for now	07-02
Callback data colon format	Compact format (select:name, list:0) stays within 64-byte limit	08-01
6 containers per page	Optimal mobile display without scrolling	08-01
Running containers first with green icon	Matches common Docker UI conventions	08-01
All keyboard transitions use editMessageText	Clean UX with no message clutter	08-01
Timestamp in confirmation callback_data	Unix seconds for 30-second timeout validation	08-02
Start/restart/logs immediate, stop/update confirm	Per user decision in context; dangerous actions need confirmation	08-02
$input.all() for Docker API responses	n8n HTTP Request splits arrays; Code nodes need to reassemble	08-03
Timestamp in logs header	Prevents Telegram "message not modified" error on refresh	08-03
Image cleanup after callback updates	Matches v1.0 text flow behavior; removes old images	08-03
Both text and button commands supported	Text commands still work alongside inline keyboard	08-03
Exact match has absolute priority	User typing exact name expects that container, not similar ones	09-01
Batch stop requires confirmation	Context specifies fuzzy matching risk for stop operations	09-01
Comma-separated names in callback	Fits within 64-byte callback_data limit for typical batch sizes	09-01
Two-phase execution for name-only containers	Callbacks from bstop/bexec have names but no IDs - need lookup first	09-02
onError: continueRegularOutput	Ensures one failure doesn't abort entire batch	09-02
Is Batch Complete IF node	Clean routing to summary instead of relying on loop second output	09-02
Warnings shown in detail for <= 3	Per context discretion - show details when few, summary when many	09-02
Update all filters to :latest containers	Performance optimization - full image check would be slow; :latest is common case	09-03
Multi-select limited to ~8 containers	64-byte callback_data limit with batch:toggle:{csv}:{name} format	09-03
Checkmark toggle UI pattern	Clear visual selection feedback; matches mobile UI conventions	09-03

Todos

• Plan Phase 6 (n8n API Access) - Complete
• Execute Phase 7 (Socket Security) - Complete
• Execute Phase 8 (Inline Keyboard Infrastructure) - Complete
• Execute Phase 9 (Batch Operations) - Complete (3/3)

Roadmap Evolution

• Phase 11 added: Documentation Overhaul
• Phase 9.1 inserted after Phase 9: Explore breaking main workflow into modular sub-workflows (URGENT)

Blockers

(none)

Deferred to Phase 9.1

• Batch Update via inline keyboard — Route Batch Loop Action "update" output is not connected. The update sequence (pull→stop→remove→create→start) is too complex to inline in the batch loop. Will be trivial once workflow is modularized into sub-workflows.

Known Limitations (64-byte callback_data)

• Long container names — Telegram's 64-byte callback_data limit causes issues with long container names in batch operations
• Batch select limited to ~2 containers — The batch:toggle:{page}:{selected}:{name} format hits the 64-byte limit quickly with multiple selections. Consider: short IDs instead of names, or storing selection state server-side in Phase 9.1

Session Continuity

• Last session: 2026-02-04
• Stopped at: Completed 09-03-PLAN.md (Phase 9 complete)
• Resume file: None
• Next step: Phase 10 - Polish & Audit

---

Auto-maintained by GSD workflow