docs(02): complete docker integration phase
Phase 2 complete with 2 plans: - 02-01: Docker socket configuration - 02-02: Docker query workflow Delivers: REQ-02 (container status queries) - "status" returns container summary - "status <name>" returns detailed container info - Fuzzy matching for container names Ready for Phase 3: Container Actions
This commit is contained in:
@@ -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*
|
||||
Reference in New Issue
Block a user