luckberg/unraid-docker-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: complete v1.1 milestone

Browse Source 
Archived:
- milestones/v1.1-ROADMAP.md
- milestones/v1.1-REQUIREMENTS.md

Deleted (fresh for next milestone):
- REQUIREMENTS.md

Updated:
- MILESTONES.md (new v1.1 entry)
- PROJECT.md (requirements → Validated, updated current state)
- ROADMAP.md (v1.1 collapsed, v1.2 phases added)
- STATE.md (reset for v1.2)

v1.1 shipped: Inline keyboard UX and Docker security hardening
- Phases 6-9 complete (11 plans)
- 4 requirements deferred to v1.2 (UNR-01, ENV-01, ENV-02, WEB-01)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lucas Berger
2026-02-04 10:55:26 -05:00
parent fa7c60394e
commit b89f78db21
6 changed files with 346 additions and 246 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.planning/milestones/v1.1-REQUIREMENTS.md
+129
View File
@@ -0,0 +1,129 @@
# Requirements Archive: v1.1 n8n Integration & Polish
**Archived:** 2026-02-04
**Status:** ✅ SHIPPED
This is the archived requirements specification for v1.1.
For current requirements, see `.planning/REQUIREMENTS.md` (created for next milestone).
---
# Requirements: Unraid Docker Manager
**Defined:** 2026-02-02
**Core Value:** Immediate container control from your phone
## v1.1 Requirements
Requirements for milestone v1.1 — n8n Integration & Polish.
### Security
- [x] **SEC-01**: Docker socket proxy deployed and configured
- [x] **SEC-02**: n8n uses socket proxy instead of direct socket mount
- [x] **SEC-03**: Socket proxy blocks dangerous APIs (exec, create, build)
- [x] **SEC-04**: All existing bot commands work through socket proxy
### n8n API
- [x] **API-01**: n8n API key created and accessible
- [x] **API-02**: Claude Code can read workflow via API
- [x] **API-03**: Claude Code can update workflow via API
- [x] **API-04**: Claude Code can view execution history and logs
### Telegram Keyboards
- [x] **KEY-01**: Status command shows container list with inline action buttons
- [x] **KEY-02**: Tapping action button performs start/stop/restart on container
- [x] **KEY-03**: Dangerous actions (stop, restart, update) show confirmation dialog
- [x] **KEY-04**: Progress shown via message edit during operations
- [x] **KEY-05**: Buttons removed after action completes
### Batch Operations
- [x] **BAT-01**: User can update multiple containers in one command
- [x] **BAT-02**: Batch updates execute sequentially with per-container feedback
- [x] **BAT-03**: "Update all" command updates all containers with updates available
- [x] **BAT-04**: "Update all" requires confirmation before executing
- [x] **BAT-05**: One container failure doesn't abort remaining batch
- [x] **BAT-06**: Final summary shows success/failure count
### Deferred to v1.2
- [ ] **UNR-01**: After bot updates a container, Unraid's update badge clears
- [ ] **ENV-01**: Verify if TELEGRAM_USERID container var is needed (vs hardcoded)
- [ ] **ENV-02**: Verify if TELEGRAM_BOT_TOKEN container var is needed (vs n8n credential)
- [ ] **WEB-01**: Fix Telegram webhook so workflow responds when published
## v1.0 Requirements (Validated)
Shipped 2026-02-02.
- [x] **MSG-01**: Send a message to the bot and receive a response
- [x] **STA-01**: Check container status ("status")
- [x] **CTL-01**: Start a container by name
- [x] **CTL-02**: Stop a container by name
- [x] **CTL-03**: Restart a container by name
- [x] **UPD-01**: Update a container (pull new image, recreate)
- [x] **LOG-01**: View container logs with configurable line count
- [x] **AUTH-01**: Bot only responds to your Telegram user ID
## Out of Scope
| Feature | Reason |
|---------|--------|
| Proactive update notifications | Bot is reactive; Unraid Telegram integration handles notifications |
| Natural language understanding | Keyword matching works well; Claude API adds complexity |
| Deploy new containers | Manage existing only; rarely needed from mobile |
| Resource monitoring queries | Deferred to future version |
| Automatic scheduled updates | User-initiated only; avoids downtime at bad times |
| MCP server for n8n | REST API simpler for v1.1; reconsider if iteration is slow |
## Traceability
| Requirement | Phase | Status |
|-------------|-------|--------|
| API-01 | Phase 6 | Complete |
| API-02 | Phase 6 | Complete |
| API-03 | Phase 6 | Complete |
| API-04 | Phase 6 | Complete |
| SEC-01 | Phase 7 | Complete |
| SEC-02 | Phase 7 | Complete |
| SEC-03 | Phase 7 | Complete |
| SEC-04 | Phase 7 | Complete |
| KEY-01 | Phase 8 | Complete |
| KEY-02 | Phase 8 | Complete |
| KEY-03 | Phase 8 | Complete |
| KEY-04 | Phase 8 | Complete |
| KEY-05 | Phase 8 | Complete |
| BAT-01 | Phase 9 | Complete |
| BAT-02 | Phase 9 | Complete |
| BAT-03 | Phase 9 | Complete |
| BAT-04 | Phase 9 | Complete |
| BAT-05 | Phase 9 | Complete |
| BAT-06 | Phase 9 | Complete |
| UNR-01 | Phase 10 | Deferred to v1.2 |
| ENV-01 | Phase 10 | Deferred to v1.2 |
| ENV-02 | Phase 10 | Deferred to v1.2 |
| WEB-01 | Phase 10 | Deferred to v1.2 |
**Coverage:**
- v1.1 requirements: 23 total
- Shipped: 19
- Deferred: 4
---
## Milestone Summary
**Shipped:** 19 of 23 v1.1 requirements
**Adjusted:**
- KEY-03: Originally "stop, restart, update" but restart was changed to immediate (low risk)
- BAT-03/BAT-04: "Update all" implemented for :latest containers only (performance optimization)
**Deferred:**
- UNR-01, ENV-01, ENV-02, WEB-01 — Moved to v1.2 Phase 10
---
*Archived: 2026-02-04 as part of v1.1 milestone completion*
.planning/milestones/v1.1-ROADMAP.md
+161
View File
@@ -0,0 +1,161 @@
# 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:
- [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
**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:
- [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
**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:
- [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...")
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:
- [x] 09-01-PLAN.md — Batch command parsing and container matching
- [x] 09-02-PLAN.md — Sequential batch execution with progress feedback
- [x] 09-03-PLAN.md — "Update all" and inline multi-select
- [x] 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_