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.md
+25
View File
@@ -1,5 +1,30 @@
# Project Milestones: Unraid Docker Manager # Project Milestones: Unraid Docker Manager
## v1.1 n8n Integration & Polish (Shipped: 2026-02-04)
**Delivered:** Inline keyboard UX and Docker security hardening — button-driven container control with filtered socket proxy.
**Phases completed:** 6-9 (11 plans total)
**Key accomplishments:**
- n8n API access for programmatic workflow management
- Docker socket proxy deployment removing direct socket exposure
- Inline keyboard with container list, pagination, and action buttons
- Batch operations with sequential execution and progress feedback
- Confirmation dialogs for dangerous actions (stop, update)
**Stats:**
- 38 files modified (+14,062/-4,239 lines)
- 8,485 lines of JSON workflow
- 4 phases, 11 plans
- 2 days (2026-02-03 → 2026-02-04)
**Git range:** `7e85697` → `fa7c603`
**What's next:** v1.2 with workflow modularization, webhook fix, environment audit, and documentation.
---
## v1.0 Docker Control via Telegram (Shipped: 2026-02-02) ## v1.0 Docker Control via Telegram (Shipped: 2026-02-02)
**Delivered:** Telegram bot for managing Docker containers on Unraid — status, start, stop, restart, update, logs via keyword commands. **Delivered:** Telegram bot for managing Docker containers on Unraid — status, start, stop, restart, update, logs via keyword commands.
.planning/PROJECT.md
+44 -28
View File
@@ -2,7 +2,7 @@
## What This Is ## What This Is
A Telegram bot that lets you manage Docker containers on your Unraid server. Control containers from your phone without needing to open a laptop — check status, view logs, start/stop/restart/update containers via simple keyword commands. A Telegram bot that lets you manage Docker containers on your Unraid server via inline keyboard buttons and text commands. Control containers from your phone without needing to open a laptop — check status, view logs, start/stop/restart/update containers, batch operations on multiple containers at once.
## Core Value ## Core Value
@@ -12,25 +12,32 @@ When you get a container update notification or notice a service is down, you ca
### Validated ### Validated
- [x] Send a message to the bot and receive a response — v1.0 **v1.0:**
- [x] Check container status ("status") — v1.0 - ✓ Send a message to the bot and receive a response — v1.0
- [x] Start a container by name — v1.0 - ✓ Check container status ("status") — v1.0
- [x] Stop a container by name — v1.0 - ✓ Start a container by name — v1.0
- [x] Restart a container by name — v1.0 - ✓ Stop a container by name — v1.0
- [x] Update a container (pull new image, recreate) — v1.0 - ✓ Restart a container by name — v1.0
- [x] View container logs with configurable line count — v1.0 - ✓ Update a container (pull new image, recreate) — v1.0
- [x] Bot only responds to your Telegram user ID — v1.0 - ✓ View container logs with configurable line count — v1.0
- ✓ Bot only responds to your Telegram user ID — v1.0
**v1.1:**
- ✓ n8n API access for Claude Code (programmatic workflow read/update/test/logs) — v1.1
- ✓ Docker socket security (remove direct socket from internet-exposed n8n) — v1.1
- ✓ Telegram inline keyboard buttons (container list with pagination and action buttons) — v1.1
- ✓ Batch container operations (update/start/stop/restart multiple at once) — v1.1
- ✓ Confirmation dialogs for dangerous actions (stop, update) — v1.1
- ✓ Progress feedback during operations (message edits) — v1.1
### Active ### Active
**Milestone v1.1: n8n Integration & Polish** **Milestone v1.2: Modularization & Polish**
- [ ] n8n API access for Claude Code (programmatic workflow read/update/test/logs) - [ ] Workflow modularization (break main workflow into sub-workflows)
- [ ] Telegram inline keyboard buttons (work around n8n native node issues)
- [ ] Batch container updates (verify/fix multi-container update)
- [ ] Docker socket security (remove direct socket from internet-exposed n8n)
- [ ] Environment variable audit (verify TELEGRAM_USERID/BOT_TOKEN necessity) - [ ] Environment variable audit (verify TELEGRAM_USERID/BOT_TOKEN necessity)
- [ ] Unraid update sync (clear "update available" when bot updates container) - [ ] Unraid update sync (clear "update available" when bot updates container)
- [ ] Telegram webhook fix (bot responds when workflow is published)
### Out of Scope ### Out of Scope
@@ -42,16 +49,18 @@ When you get a container update notification or notice a service is down, you ca
## Current State ## Current State
**Shipped:** v1.0 (2026-02-02) **Shipped:** v1.1 (2026-02-04)
**Tech stack:** n8n workflow + Telegram Bot API + Docker socket **Tech stack:** n8n workflow + Telegram Bot API + Docker socket proxy
**Files:** n8n-workflow.json (~3,200 lines), README.md **Files:** n8n-workflow.json (~8,500 lines), README.md
**Architecture:** tecnativa/docker-socket-proxy filters Docker API access
## Context ## Context
**Environment:** **Environment:**
- Unraid server with Intel N100 CPU, 32GB RAM - Unraid server with Intel N100 CPU, 32GB RAM
- n8n container with Docker socket access - n8n container with Docker socket proxy access (no direct socket mount)
- Multiple Docker containers (Plex, Sonarr, lldap, etc.) - Multiple Docker containers (Plex, Sonarr, lldap, etc.)
- docker-socket-proxy on dockernet network
**Constraints:** **Constraints:**
- Platform: Unraid (Docker-based) - Platform: Unraid (Docker-based)
@@ -59,6 +68,7 @@ When you get a container update notification or notice a service is down, you ca
- Matching: Keyword/substring with exact-match priority - Matching: Keyword/substring with exact-match priority
- Auth: Single user via Telegram ID - Auth: Single user via Telegram ID
- Logs: Configurable line count, default 50, max 1000 - Logs: Configurable line count, default 50, max 1000
- Callback data: 64-byte Telegram limit (affects batch/selection features)
## Key Decisions ## Key Decisions
@@ -72,19 +82,25 @@ When you get a container update notification or notice a service is down, you ca
| Exact match priority | Prevents substring collisions (plex vs jellyplex) | ✓ Good | | Exact match priority | Prevents substring collisions (plex vs jellyplex) | ✓ Good |
| Default to :latest tag | Prevents Docker API from pulling all tags | ✓ Good | | Default to :latest tag | Prevents Docker API from pulling all tags | ✓ Good |
| HTML escape logs | Log content may contain <tag> text | ✓ Good | | HTML escape logs | Log content may contain <tag> text | ✓ Good |
| Text menu over keyboard | Native Telegram node replyKeyboard had issues | ✓ Good | | docker-socket-proxy for security | Filters dangerous APIs (exec, build, commit) at network level | ✓ Good |
| Container create API allowed | Update command needs container recreation | ✓ Good |
| Colon callback format | Compact format fits 64-byte limit | ✓ Good |
| editMessageText transitions | Clean UX with no message clutter | ✓ Good |
| 30-second confirmation timeout | Prevents stale confirmations | ✓ Good |
| Batch stop requires confirmation | Fuzzy matching risk for destructive operations | ✓ Good |
| Two-phase batch execution | Callbacks have names but no IDs - need lookup | ✓ Good |
| Update all filters to :latest | Performance optimization - full check would be slow | ✓ Good |
## Current Milestone: v1.1 n8n Integration & Polish ## Current Milestone: v1.2 Modularization & Polish
**Goal:** Enable faster development iteration via n8n API access, revisit UX improvements (buttons), and harden security (remove direct Docker socket exposure). **Goal:** Complete remaining v1.1 scope — modularize workflow for maintainability, fix webhook, audit environment, sync Unraid badges.
**Target features:** **Target features:**
- n8n API for Claude Code — programmatic workflow access - Workflow modularization (carried from Phase 9.1)
- Telegram inline keyboard buttons — better UX than text menus - Webhook fix (WEB-01)
- Batch container updates — update multiple at once - Environment audit (ENV-01, ENV-02)
- Docker socket security — remove direct exposure - Unraid badge sync (UNR-01)
- Environment variable audit — verify what's needed - Documentation overhaul
- Unraid update sync — clear notifications properly
--- ---
*Last updated: 2026-02-02 after starting v1.1 milestone* *Last updated: 2026-02-04 after v1.1 milestone*
.planning/ROADMAP.md
+31 -117
View File
@@ -3,133 +3,46 @@
## Milestones ## Milestones
- **v1.0 Docker Control via Telegram** — Phases 1-5 (shipped 2026-02-02) -> [Archive](milestones/v1.0-ROADMAP.md) - **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** — Phases 6-9 (shipped 2026-02-04) -> [Archive](milestones/v1.1-ROADMAP.md)
- **v1.2 Modularization & Polish** — Phases 10-12 (planned)
--- ---
## v1.1: n8n Integration & Polish ## v1.2: Modularization & 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. Complete remaining v1.1 scope: modularize workflow for maintainability, fix webhook issues, audit environment variables, and clear Unraid update badges.
### Phase 6: n8n API Access ### Phase 10: Workflow Modularization
**Goal:** Claude Code can programmatically read, update, and test workflows **Goal:** Break main workflow into modular sub-workflows for maintainability
**Dependencies:** None (enables faster iteration on all subsequent phases) **Dependencies:** None
**Requirements:** API-01, API-02, API-03, API-04 **Requirements:** TBD (carried from Phase 9.1)
**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:** 0 plans
Plans: Plans:
- [ ] TBD (run /gsd:plan-phase 9.1 to break down) - [ ] TBD (run /gsd:plan-phase 10 to break down)
**Success Criteria:** **Success Criteria:**
[To be defined during planning] [To be defined during planning]
--- ---
### Phase 10: Polish & Audit ### Phase 11: Polish & Audit
**Goal:** Clear Unraid update badges, fix webhook issues, and verify environment configuration **Goal:** Clear Unraid update badges, fix webhook issues, and verify environment configuration
**Dependencies:** Phase 9.1 (workflow modularization complete before polish) **Dependencies:** Phase 10 (modularization complete before polish)
**Requirements:** UNR-01, ENV-01, ENV-02, WEB-01 **Requirements:** UNR-01, ENV-01, ENV-02, WEB-01
**Plans:** 0 plans
Plans:
- [ ] TBD (run /gsd:plan-phase 11 to break down)
**Success Criteria:** **Success Criteria:**
1. After bot successfully updates a container, Unraid UI no longer shows "update available" for that container 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 2. Documentation clarifies whether TELEGRAM_USERID env var is required or can be hardcoded
@@ -138,18 +51,18 @@ Plans:
--- ---
### Phase 11: Documentation Overhaul ### Phase 12: Documentation Overhaul
**Goal:** [To be planned] **Goal:** [To be planned]
**Dependencies:** Phase 10 (core features complete before documentation) **Dependencies:** Phase 11 (core features complete before documentation)
**Requirements:** TBD **Requirements:** TBD
**Plans:** 0 plans **Plans:** 0 plans
Plans: Plans:
- [ ] TBD (run /gsd:plan-phase 11 to break down) - [ ] TBD (run /gsd:plan-phase 12 to break down)
**Success Criteria:** **Success Criteria:**
[To be defined during planning] [To be defined during planning]
@@ -158,17 +71,18 @@ Plans:
## Progress ## Progress
| Phase | Name | Requirements | Status | | Phase | Name | Milestone | Status |
|-------|------|--------------|--------| |-------|------|-----------|--------|
| 6 | n8n API Access | API-01, API-02, API-03, API-04 | Complete | | 1-5 | Foundation through Polish | v1.0 | Complete |
| 7 | Socket Security | SEC-01, SEC-02, SEC-03, SEC-04 | Complete | | 6 | n8n API Access | v1.1 | Complete |
| 8 | Inline Keyboard Infrastructure | KEY-01, KEY-02, KEY-03, KEY-04, KEY-05 | Complete | | 7 | Socket Security | v1.1 | Complete |
| 9 | Batch Operations | BAT-01, BAT-02, BAT-03, BAT-04, BAT-05, BAT-06 | Pending | | 8 | Inline Keyboard Infrastructure | v1.1 | Complete |
| 9.1 | Explore Modular Sub-Workflows | TBD | Pending | | 9 | Batch Operations | v1.1 | Complete |
| 10 | Polish & Audit | UNR-01, ENV-01, ENV-02, WEB-01 | Pending | | 10 | Workflow Modularization | v1.2 | Pending |
| 11 | Documentation Overhaul | TBD | Pending | | 11 | Polish & Audit | v1.2 | Pending |
| 12 | Documentation Overhaul | v1.2 | Pending |
**v1.1 Coverage:** 23/23 requirements mapped (Phase 11 TBD) **v1.2 Coverage:** 4 requirements mapped (UNR-01, ENV-01, ENV-02, WEB-01), modularization TBD
--- ---
*Updated: 2026-02-03* *Updated: 2026-02-04 after v1.1 milestone*
.planning/STATE.md
+31 -63
View File
@@ -2,101 +2,69 @@
## Project Reference ## Project Reference
See: .planning/PROJECT.md (updated 2026-02-02) See: .planning/PROJECT.md (updated 2026-02-04)
**Core value:** Immediate container control from your phone **Core value:** Immediate container control from your phone
**Current focus:** v1.1 Phase 9 in progress — batch execution and progress complete **Current focus:** v1.2 — Planning next milestone
## Current Position ## Current Position
- **Milestone:** v1.1 — n8n Integration & Polish - **Milestone:** v1.2 — Modularization & Polish
- **Phase:** 9 of 11 (Batch Operations) - **Phase:** 10 of 12 (Workflow Modularization)
- **Plan:** 4 of 4 complete (including verification) - **Plan:** Not started
- **Status:** Phase complete and verified - **Status:** Ready to plan
- **Last activity:** 2026-02-04 — Completed 09-04 verification testing - **Last activity:** 2026-02-04 — v1.1 milestone complete
## Progress ## Progress
``` ```
v1.1: [████████░ ] 81% v1.0: [██████████] 100% SHIPPED
v1.1: [██████████] 100% SHIPPED
Phase 6: n8n API Access [##########] Complete v1.2: [ ] 0%
Phase 7: Socket Security [##########] Complete (3/3)
Phase 8: Inline Keyboard Infra [##########] Complete (3/3) Phase 10: Workflow Modularization [ ] Pending
Phase 9: Batch Operations [##########] Complete (3/3) Phase 11: Polish & Audit [ ] Pending
Phase 10: Polish & Audit [ ] Pending Phase 12: Documentation Overhaul [ ] Pending
Phase 11: Documentation Overhaul [ ] Pending
``` ```
## Accumulated Context ## Accumulated Context
### Key Decisions ### Key Decisions
| Decision | Rationale | Phase | See PROJECT.md Key Decisions table for full history.
|----------|-----------|-------|
| n8n API first | Enables faster iteration on all subsequent phases | 6 | Recent v1.1 decisions:
| n8n API key never expires | Development environment on private network, rotation not critical | 06-01 | - docker-socket-proxy for filtered Docker API access
| .env.n8n-api filename | Specific purpose, won't conflict with future env files | 06-01 | - Colon-separated callback format for 64-byte compliance
| docker-socket-proxy deployed via user action | Consistent with Unraid-native approach, user has direct GUI access | 07-01 | - Two-phase batch execution for name-only callbacks
| dockernet network for n8n and proxy | Custom bridge network provides DNS resolution between containers | 07-01 | - Update all filters to :latest containers only
| 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 ### Todos
- [x] Plan Phase 6 (n8n API Access) - Complete (none — fresh milestone)
- [x] Execute Phase 7 (Socket Security) - Complete
- [x] Execute Phase 8 (Inline Keyboard Infrastructure) - Complete
- [x] Execute Phase 9 (Batch Operations) - Complete and verified (4/4)
### Roadmap Evolution
- Phase 11 added: Documentation Overhaul
- Phase 9.1 inserted after Phase 9: Explore breaking main workflow into modular sub-workflows (URGENT)
### Blockers ### Blockers
(none) (none)
### Deferred to Phase 9.1 ### Known Limitations
- **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. - **64-byte callback_data limit** — Affects batch selection and long container names
- **Batch update via inline keyboard** — Deferred to Phase 10 (needs modularization)
- **Webhook only works via manual execute** — WEB-01 in Phase 11
### Known Limitations (64-byte callback_data) ### Technical Debt
- **Long container names** — Telegram's 64-byte callback_data limit causes issues with long container names in batch operations - Update flow duplicated between single and batch paths
- **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 - Workflow at 8,485 lines (growing complexity)
## Session Continuity ## Session Continuity
- **Last session:** 2026-02-04 - **Last session:** 2026-02-04
- **Stopped at:** Phase 9 verification complete - **Stopped at:** v1.1 milestone completion
- **Resume file:** None - **Resume file:** None
- **Next step:** Phase 10 - Polish & Audit - **Next step:** `/gsd:new-milestone` to define v1.2 requirements and roadmap
--- ---
*Auto-maintained by GSD workflow* *Auto-maintained by GSD workflow*
.planning/REQUIREMENTS.md → .planning/milestones/v1.1-REQUIREMENTS.md
+54 -38
View File
@@ -1,3 +1,13 @@
# 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 # Requirements: Unraid Docker Manager
**Defined:** 2026-02-02 **Defined:** 2026-02-02
@@ -23,33 +33,27 @@ Requirements for milestone v1.1 — n8n Integration & Polish.
### Telegram Keyboards ### Telegram Keyboards
- [ ] **KEY-01**: Status command shows container list with inline action buttons - [x] **KEY-01**: Status command shows container list with inline action buttons
- [ ] **KEY-02**: Tapping action button performs start/stop/restart on container - [x] **KEY-02**: Tapping action button performs start/stop/restart on container
- [ ] **KEY-03**: Dangerous actions (stop, restart, update) show confirmation dialog - [x] **KEY-03**: Dangerous actions (stop, restart, update) show confirmation dialog
- [ ] **KEY-04**: Progress shown via message edit during operations - [x] **KEY-04**: Progress shown via message edit during operations
- [ ] **KEY-05**: Buttons removed after action completes - [x] **KEY-05**: Buttons removed after action completes
### Batch Operations ### Batch Operations
- [ ] **BAT-01**: User can update multiple containers in one command - [x] **BAT-01**: User can update multiple containers in one command
- [ ] **BAT-02**: Batch updates execute sequentially with per-container feedback - [x] **BAT-02**: Batch updates execute sequentially with per-container feedback
- [ ] **BAT-03**: "Update all" command updates all containers with updates available - [x] **BAT-03**: "Update all" command updates all containers with updates available
- [ ] **BAT-04**: "Update all" requires confirmation before executing - [x] **BAT-04**: "Update all" requires confirmation before executing
- [ ] **BAT-05**: One container failure doesn't abort remaining batch - [x] **BAT-05**: One container failure doesn't abort remaining batch
- [ ] **BAT-06**: Final summary shows success/failure count - [x] **BAT-06**: Final summary shows success/failure count
### Unraid Sync ### Deferred to v1.2
- [ ] **UNR-01**: After bot updates a container, Unraid's update badge clears - [ ] **UNR-01**: After bot updates a container, Unraid's update badge clears
### Environment Audit
- [ ] **ENV-01**: Verify if TELEGRAM_USERID container var is needed (vs hardcoded) - [ ] **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) - [ ] **ENV-02**: Verify if TELEGRAM_BOT_TOKEN container var is needed (vs n8n credential)
- [ ] **WEB-01**: Fix Telegram webhook so workflow responds when published
### Webhook
- [ ] **WEB-01**: Fix Telegram webhook so workflow responds when published (currently only works with manual execute)
## v1.0 Requirements (Validated) ## v1.0 Requirements (Validated)
@@ -87,27 +91,39 @@ Shipped 2026-02-02.
| SEC-02 | Phase 7 | Complete | | SEC-02 | Phase 7 | Complete |
| SEC-03 | Phase 7 | Complete | | SEC-03 | Phase 7 | Complete |
| SEC-04 | Phase 7 | Complete | | SEC-04 | Phase 7 | Complete |
| KEY-01 | Phase 8 | Pending | | KEY-01 | Phase 8 | Complete |
| KEY-02 | Phase 8 | Pending | | KEY-02 | Phase 8 | Complete |
| KEY-03 | Phase 8 | Pending | | KEY-03 | Phase 8 | Complete |
| KEY-04 | Phase 8 | Pending | | KEY-04 | Phase 8 | Complete |
| KEY-05 | Phase 8 | Pending | | KEY-05 | Phase 8 | Complete |
| BAT-01 | Phase 9 | Pending | | BAT-01 | Phase 9 | Complete |
| BAT-02 | Phase 9 | Pending | | BAT-02 | Phase 9 | Complete |
| BAT-03 | Phase 9 | Pending | | BAT-03 | Phase 9 | Complete |
| BAT-04 | Phase 9 | Pending | | BAT-04 | Phase 9 | Complete |
| BAT-05 | Phase 9 | Pending | | BAT-05 | Phase 9 | Complete |
| BAT-06 | Phase 9 | Pending | | BAT-06 | Phase 9 | Complete |
| UNR-01 | Phase 10 | Pending | | UNR-01 | Phase 10 | Deferred to v1.2 |
| ENV-01 | Phase 10 | Pending | | ENV-01 | Phase 10 | Deferred to v1.2 |
| ENV-02 | Phase 10 | Pending | | ENV-02 | Phase 10 | Deferred to v1.2 |
| WEB-01 | Phase 10 | Pending | | WEB-01 | Phase 10 | Deferred to v1.2 |
**Coverage:** **Coverage:**
- v1.1 requirements: 23 total - v1.1 requirements: 23 total
- Mapped to phases: 22 - Shipped: 19
- Unmapped: 0 - Deferred: 4
--- ---
*Requirements defined: 2026-02-02*
*Last updated: 2026-02-02 after roadmap creation* ## 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_