Files

T

Lucas Berger af5397306d 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

2026-01-29 14:43:13 -05:00

3.4 KiB

Raw Permalink Blame History

phase, plan, subsystem, tags, requires, provides, affects, tech-stack, key-files, key-decisions, patterns-established, duration, completed

phase

plan

subsystem

tags

requires

provides

affects

tech-stack

key-files

key-decisions

patterns-established

duration

completed

02-docker-integration

api

n8n

docker-api

fuzzy-matching

workflow

phase	provides
02-docker-integration/01	Docker socket access from n8n container

phase	provides
01-foundation	Telegram trigger and authentication workflow

Docker container status queries via Telegram

Fuzzy container name matching

Summary and detailed container views

03-container-actions

04-logs-intelligence

added

patterns

execute-command-curl

switch-routing

fuzzy-match

created

modified

n8n-workflow.json

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)

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

~30min

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

Task 1: Add Docker Query Branch to Workflow - 1252ff4 (feat)
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

3.4 KiB Raw Permalink Blame History