diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index fe7f037..0561633 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -35,10 +35,10 @@ Plans: **Plans:** 2 plans Plans: -- [ ] 02-01-PLAN.md β€” Configure n8n container for Docker socket access -- [ ] 02-02-PLAN.md β€” Add Docker query workflow with container matching +- [x] 02-01-PLAN.md β€” Configure n8n container for Docker socket access +- [x] 02-02-PLAN.md β€” Add Docker query workflow with container matching -**Status:** πŸ”„ Planning complete +**Status:** βœ… Complete (2026-01-29) --- diff --git a/.planning/STATE.md b/.planning/STATE.md index 22a2877..89e21f9 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -8,21 +8,21 @@ ## Current Position - **Milestone:** v1.0 β€” Conversational Docker Control -- **Phase:** 2 of 5 β€” Docker Integration (IN PROGRESS) -- **Plan:** 1 of 2 complete -- **Status:** Executing Phase 2 -- **Last activity:** 2026-01-29 - Completed 02-01-PLAN.md +- **Phase:** 2 of 5 β€” Docker Integration (COMPLETE) +- **Plan:** 2 of 2 complete +- **Status:** Phase 2 complete, ready for Phase 3 +- **Last activity:** 2026-01-29 - Completed 02-02-PLAN.md ## Progress ``` Phase 1: Foundation [β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆ] Complete (2/2 plans) -Phase 2: Docker Integration [β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘] In progress (1/2 plans) +Phase 2: Docker Integration [β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆ] Complete (2/2 plans) Phase 3: Container Actions πŸ”² Not started Phase 4: Logs & IntelligenceπŸ”² Not started Phase 5: Polish & Deploy πŸ”² Not started -Overall: [β–ˆβ–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘β–‘β–‘] 30% +Overall: [β–ˆβ–ˆβ–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘β–‘] 40% ``` ## Recent Decisions @@ -37,6 +37,8 @@ Overall: [β–ˆβ–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘β–‘β–‘] 30% | HTML parse mode | Future formatting flexibility for responses | 2026-01-28 | | Static curl binary mount | Hardened n8n image lacks package manager | 2026-01-29 | | --group-add 281 for socket | Node user needs docker group for socket access | 2026-01-29 | +| curl -s flag for silent mode | Prevents stderr progress output causing false errors | 2026-01-29 | +| Substring matching for containers | Simple approach works well, no external library needed | 2026-01-29 | ## Pending Todos @@ -49,9 +51,9 @@ Overall: [β–ˆβ–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘β–‘β–‘] 30% ## Session Continuity - **Last session:** 2026-01-29 -- **Stopped at:** Completed 02-01-PLAN.md (Docker Socket Configuration) +- **Stopped at:** Completed Phase 2 (Docker Integration) - **Resume file:** None -- **Next step:** Execute 02-02-PLAN.md (Docker Query Workflow) +- **Next step:** Plan Phase 3 - Container Actions --- *Auto-maintained by GSD workflow* diff --git a/.planning/phases/02-docker-integration/02-02-SUMMARY.md b/.planning/phases/02-docker-integration/02-02-SUMMARY.md new file mode 100644 index 0000000..4510600 --- /dev/null +++ b/.planning/phases/02-docker-integration/02-02-SUMMARY.md @@ -0,0 +1,114 @@ +--- +phase: 02-docker-integration +plan: 02 +subsystem: api +tags: [n8n, docker-api, telegram, fuzzy-matching, workflow] + +requires: + - phase: 02-docker-integration/01 + provides: Docker socket access from n8n container + - phase: 01-foundation + provides: Telegram trigger and authentication workflow + +provides: + - Docker container status queries via Telegram + - Fuzzy container name matching + - Summary and detailed container views + +affects: [03-container-actions, 04-logs-intelligence] + +tech-stack: + added: [] + patterns: [execute-command-curl, switch-routing, fuzzy-match] + +key-files: + created: [] + modified: [n8n-workflow.json] + +key-decisions: + - "Use curl -s flag to suppress stderr progress output" + - "Only validate stdout JSON, ignore stderr for error detection" + - "Simple substring matching for container names (no external library)" + +patterns-established: + - "Execute Command node with curl for Docker API queries" + - "Code nodes for JSON parsing and response formatting" + - "Switch node for message routing based on content" + +duration: ~30min +completed: 2026-01-29 +--- + +# Phase 2 Plan 02: Docker Query Workflow Summary + +**n8n workflow extended with Docker query capability - status summaries and container details via Telegram** + +## Performance + +- **Duration:** ~30 min +- **Started:** 2026-01-29T14:35:00Z +- **Completed:** 2026-01-29T15:05:00Z +- **Tasks:** 3 +- **Files modified:** 1 + +## Accomplishments + +- Added Switch node to route "status" messages to Docker query branch +- Execute Command node queries Docker API via Unix socket with curl +- Code nodes parse JSON, implement fuzzy container name matching, and format responses +- Emoji status indicators (βœ… running, ❌ stopped, etc.) +- Summary view shows container counts by state +- Detail view shows name, state, status, image, and ID +- Echo branch preserved for non-docker messages + +## Task Commits + +1. **Task 1: Add Docker Query Branch to Workflow** - `1252ff4` (feat) +2. **Bug fix: False positive docker error** - `8e155c5` (fix) + +**Plan metadata:** (this commit) + +## Files Created/Modified + +- `n8n-workflow.json` - Extended with Docker query branch (5 new nodes) + +## Decisions Made + +| Decision | Rationale | +|----------|-----------| +| Use curl -s (silent) flag | Suppresses progress output to stderr that caused false error detection | +| Validate only stdout for errors | stderr contains curl progress info even on success | +| Simple substring matching | No external library needed, works well for container names | +| Strip linuxserver-/binhex- prefixes | Common Unraid container naming patterns | + +## Deviations from Plan + +### Bug Fix: stderr False Positive + +- **Found during:** Task 3 (verification) +- **Issue:** curl writes progress to stderr even on success, triggering error handler +- **Fix:** Added -s flag to curl, changed error check to only validate stdout JSON +- **Committed in:** 8e155c5 + +--- + +**Total deviations:** 1 bug fix during verification +**Impact on plan:** Minor fix, no scope change + +## Issues Encountered + +- Initial error handling checked for any stderr content, but curl writes progress info there even on success. Fixed by using -s flag and only checking stdout validity. + +## User Setup Required + +None - workflow file updated, user imports into n8n. + +## Next Phase Readiness + +- Docker query capability complete and verified +- Foundation ready for Phase 3: Container Actions (start/stop/restart) +- Fuzzy matching pattern established for reuse in action commands + +--- +*Phase: 02-docker-integration* +*Completed: 2026-01-29*