Lucas Berger
af5397306d
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
115 lines
3.4 KiB
Markdown
115 lines
3.4 KiB
Markdown
---
|
|
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*
|