unraid-docker-manager/.planning/milestones/v1.1-ROADMAP.md

Milestone v1.1: n8n Integration & Polish

Status: ✅ SHIPPED 2026-02-04 Phases: 6-9 Total Plans: 11

Overview

Enable faster development iteration via n8n API access, improve UX with inline keyboard buttons, add batch operations, and harden security by removing direct Docker socket exposure from n8n.

Phases

Phase 6: n8n API Access

Goal: Claude Code can programmatically read, update, and test workflows

Depends on: None (enables faster iteration on all subsequent phases)

Requirements: API-01, API-02, API-03, API-04

Plans: 1 plan

Plans:

• 06-01-PLAN.md — Enable API access (create key, verify CRUD, execution history)

Success Criteria:

1. ✅ n8n API key exists and Claude Code can authenticate against the n8n API
2. ✅ Claude Code can retrieve the current workflow JSON via API call
3. ✅ Claude Code can push workflow changes via API and they take effect immediately
4. ✅ Claude Code can view execution history showing recent runs with success/failure status

Details:

• n8n API authentication via X-N8N-API-KEY header
• Workflow ID: HmiXBlJefBRPMS0m4iNYc
• Credentials stored in .env.n8n-api (gitignored)
• Full CRUD operations verified

---

Phase 7: Socket Security

Goal: Docker operations flow through a filtered proxy instead of direct socket access

Depends on: Phase 6 (API access enables faster iteration on curl command migration)

Requirements: SEC-01, SEC-02, SEC-03, SEC-04

Plans: 3 plans

Plans:

• 07-01-PLAN.md — Deploy docker-socket-proxy via Unraid CA
• 07-02-PLAN.md — Migrate workflow curl commands to proxy
• 07-03-PLAN.md — Verify dangerous APIs are blocked

Success Criteria:

1. ✅ Socket proxy container runs on internal network with Docker socket mounted
2. ✅ n8n container connects to proxy via TCP instead of mounting docker.sock directly
3. ✅ Dangerous Docker APIs (exec, create, build) return blocked/forbidden responses
4. ✅ All existing bot commands (status, start, stop, restart, update, logs) work identically through proxy

Details:

• tecnativa/docker-socket-proxy deployed on dockernet network
• 16 curl commands migrated from unix socket to TCP proxy
• Exec, build, commit APIs blocked (403 Forbidden)
• Container create allowed for update command functionality
• docker.sock mount removed from n8n container

---

Phase 8: Inline Keyboard Infrastructure

Goal: Users interact with containers via tappable buttons instead of typing commands

Depends on: Phase 7 (security in place before adding new features)

Requirements: KEY-01, KEY-02, KEY-03, KEY-04, KEY-05

Plans: 3 plans

Plans:

• 08-01-PLAN.md — Container list keyboard and submenu navigation
• 08-02-PLAN.md — Action execution and confirmation flow
• 08-03-PLAN.md — Progress feedback and completion messages

Success Criteria:

1. ✅ Status command returns a message with inline buttons showing available actions per container
2. ✅ Tapping an action button (start/stop/restart) executes that action on the target container
3. ✅ Dangerous actions (stop, update) show a confirmation prompt before executing
4. ✅ During operation execution, the message updates to show progress (e.g., "Updating...")
5. ✅ After action completes, buttons are removed and final status is shown in the message

Details:

• Callback data format: colon-separated for 64-byte compliance
• 6 containers per page with pagination
• Running containers first with green circle icon
• All transitions use editMessageText (no message clutter)
• 30-second confirmation timeout with cancel option
• 37 new nodes added for action execution and confirmation

---

Phase 9: Batch Operations

Goal: Users can update multiple containers in a single command with clear feedback

Depends on: Phase 8 (keyboard infrastructure supports confirmation dialogs)

Requirements: BAT-01, BAT-02, BAT-03, BAT-04, BAT-05, BAT-06

Plans: 4 plans

Plans:

• 09-01-PLAN.md — Batch command parsing and container matching
• 09-02-PLAN.md — Sequential batch execution with progress feedback
• 09-03-PLAN.md — "Update all" and inline multi-select
• 09-04-PLAN.md — Verification and testing

Success Criteria:

1. ✅ User can type "stop container1 container2" and all containers stop sequentially
2. ✅ Each container shows individual progress/result as it completes (not waiting until all finish)
3. ⏸️ "Update all" command shows confirmation with list of containers before executing (testing deferred)
4. ✅ If one container fails mid-batch, remaining containers still attempt to execute
5. ✅ Final message shows summary: "3 updated, 1 failed" with details

Details:

• Exact-match priority in container matching
• Two-phase execution for name-only callbacks
• onError: continueRegularOutput for non-aborting batch
• 64-byte callback_data limit enforced (~8 containers max in multi-select)
• Checkmark toggle UI for visual selection feedback

---

Milestone Summary

Key Decisions:

• n8n API key with never-expire policy for development
• docker-socket-proxy for filtered Docker API access
• Colon-separated callback format for 64-byte compliance
• Exact match priority in container matching
• Stop/update require confirmation; start/restart/logs immediate

Issues Resolved:

• Telegram webhook only works via manual execute (deferred to WEB-01)
• Array handling in n8n Code nodes ($input.all() pattern)
• Message edit conflicts with identical content (timestamp solution)

Issues Deferred:

• Batch update via inline keyboard (complex sequence, needs modularization)
• Webhook fix (WEB-01 in Phase 10)
• Environment variable audit (Phase 10)
• Unraid update badge sync (Phase 10)

Technical Debt Incurred:

• Update flow duplicated between single and batch paths
• Workflow now 8,485 lines (complexity growing)
• Long container names hit 64-byte callback limit

---

For current project status, see .planning/ROADMAP.md