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

# Roadmap — Unraid Docker Manager

## Milestones

- **v1.0 Docker Control via Telegram** — Phases 1-5 (shipped 2026-02-02) -> [Archive](milestones/v1.0-ROADMAP.md)
- **v1.1 n8n Integration & Polish** — Phases 6-10 (in progress)

---

## v1.1: n8n Integration & Polish

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.

### Phase 6: n8n API Access

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

**Dependencies:** None (enables faster iteration on all subsequent phases)

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

**Plans:** 1 plan

Plans:
- [x] 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

---

### Phase 7: Socket Security

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

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

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

**Plans:** 3 plans

Plans:
- [x] 07-01-PLAN.md — Deploy docker-socket-proxy via Unraid CA
- [x] 07-02-PLAN.md — Migrate workflow curl commands to proxy
- [x] 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

---

### Phase 8: Inline Keyboard Infrastructure

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

**Dependencies:** Phase 7 (security in place before adding new features)

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

**Plans:** 3 plans

Plans:
- [x] 08-01-PLAN.md — Container list keyboard and submenu navigation
- [x] 08-02-PLAN.md — Action execution and confirmation flow
- [x] 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 plex...")
5. After action completes, buttons are removed and final status is shown in the message

---

### Phase 9: Batch Operations

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

**Dependencies:** 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 "update plex sonarr radarr" and all three containers update 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
4. If one container fails mid-batch, remaining containers still attempt to update
5. Final message shows summary: "3 updated, 1 failed" with details

---

### Phase 9.1: Explore Breaking Main Workflow into Modular Sub-Workflows (INSERTED)

**Goal:** [Urgent work - to be planned]

**Dependencies:** Phase 9 (batch operations complete before modularization)

**Requirements:** TBD

**Plans:** 0 plans

Plans:
- [ ] TBD (run /gsd:plan-phase 9.1 to break down)

**Success Criteria:**
[To be defined during planning]

---

### Phase 10: Polish & Audit

**Goal:** Clear Unraid update badges, fix webhook issues, and verify environment configuration

**Dependencies:** Phase 9.1 (workflow modularization complete before polish)

**Requirements:** UNR-01, ENV-01, ENV-02, WEB-01

**Success Criteria:**
1. After bot successfully updates a container, Unraid UI no longer shows "update available" for that container
2. Documentation clarifies whether TELEGRAM_USERID env var is required or can be hardcoded
3. Documentation clarifies whether TELEGRAM_BOT_TOKEN env var is required or if n8n credential suffices
4. Telegram webhook works when workflow is published (bot responds without manual execute)

---

### Phase 11: Documentation Overhaul

**Goal:** [To be planned]

**Dependencies:** Phase 10 (core features complete before documentation)

**Requirements:** TBD

**Plans:** 0 plans

Plans:
- [ ] TBD (run /gsd:plan-phase 11 to break down)

**Success Criteria:**
[To be defined during planning]

---

## Progress

| Phase | Name | Requirements | Status |
|-------|------|--------------|--------|
| 6 | n8n API Access | API-01, API-02, API-03, API-04 | Complete |
| 7 | Socket Security | SEC-01, SEC-02, SEC-03, SEC-04 | Complete |
| 8 | Inline Keyboard Infrastructure | KEY-01, KEY-02, KEY-03, KEY-04, KEY-05 | Complete |
| 9 | Batch Operations | BAT-01, BAT-02, BAT-03, BAT-04, BAT-05, BAT-06 | Pending |
| 9.1 | Explore Modular Sub-Workflows | TBD | Pending |
| 10 | Polish & Audit | UNR-01, ENV-01, ENV-02, WEB-01 | Pending |
| 11 | Documentation Overhaul | TBD | Pending |

**v1.1 Coverage:** 23/23 requirements mapped (Phase 11 TBD)

---
*Updated: 2026-02-03*