docs(02-01): complete docker socket configuration plan
Tasks completed: 3/3 - Configure n8n container for Docker access - Verify Docker API access - Confirm Docker access working Decisions: - Static curl binary mount (hardened image lacks apk) - --group-add 281 for docker socket permissions SUMMARY: .planning/phases/02-docker-integration/02-01-SUMMARY.md
This commit is contained in:
Lucas Berger
+11
-9
@@ -8,21 +8,21 @@
|
||||
## Current Position
|
||||
|
||||
- **Milestone:** v1.0 — Conversational Docker Control
|
||||
- **Phase:** 1 of 5 — Foundation (COMPLETE)
|
||||
- **Plan:** 2 of 2 complete
|
||||
- **Status:** Phase 1 complete, ready for Phase 2
|
||||
- **Last activity:** 2026-01-28 - Completed 01-02-PLAN.md
|
||||
- **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
|
||||
|
||||
## Progress
|
||||
|
||||
```
|
||||
Phase 1: Foundation [██████████] Complete (2/2 plans)
|
||||
Phase 2: Docker Integration 🔲 Not started
|
||||
Phase 2: Docker Integration [█████░░░░░] In progress (1/2 plans)
|
||||
Phase 3: Container Actions 🔲 Not started
|
||||
Phase 4: Logs & Intelligence🔲 Not started
|
||||
Phase 5: Polish & Deploy 🔲 Not started
|
||||
|
||||
Overall: [██░░░░░░░░] 20%
|
||||
Overall: [███░░░░░░░] 30%
|
||||
```
|
||||
|
||||
## Recent Decisions
|
||||
@@ -35,6 +35,8 @@ Overall: [██░░░░░░░░] 20%
|
||||
| Hardcoded user ID in workflow | n8n CE blocks env var access in expressions | 2026-01-28 |
|
||||
| Silent ignore unauthorized | No false branch nodes, prevents information leak | 2026-01-28 |
|
||||
| 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 |
|
||||
|
||||
## Pending Todos
|
||||
|
||||
@@ -46,10 +48,10 @@ Overall: [██░░░░░░░░] 20%
|
||||
|
||||
## Session Continuity
|
||||
|
||||
- **Last session:** 2026-01-28
|
||||
- **Stopped at:** Completed 01-02-PLAN.md (Workflow Import and Verification)
|
||||
- **Last session:** 2026-01-29
|
||||
- **Stopped at:** Completed 02-01-PLAN.md (Docker Socket Configuration)
|
||||
- **Resume file:** None
|
||||
- **Next step:** Plan Phase 2 - Docker Integration
|
||||
- **Next step:** Execute 02-02-PLAN.md (Docker Query Workflow)
|
||||
|
||||
---
|
||||
*Auto-maintained by GSD workflow*
|
||||
|
||||
@@ -0,0 +1,129 @@
|
||||
---
|
||||
phase: 02-docker-integration
|
||||
plan: 01
|
||||
subsystem: infra
|
||||
tags: [docker, n8n, unraid, unix-socket, curl]
|
||||
|
||||
requires:
|
||||
- phase: 01-foundation
|
||||
provides: n8n workflow with Telegram integration
|
||||
|
||||
provides:
|
||||
- Docker socket access from n8n container
|
||||
- curl binary with Unix socket support
|
||||
- Execute Command node enabled in n8n
|
||||
|
||||
affects: [02-docker-integration, 03-container-actions]
|
||||
|
||||
tech-stack:
|
||||
added: [static-curl]
|
||||
patterns: [unix-socket-api-access, volume-mount-binaries]
|
||||
|
||||
key-files:
|
||||
created: []
|
||||
modified: [n8n container configuration]
|
||||
|
||||
key-decisions:
|
||||
- "Mount static curl binary instead of installing via package manager (hardened image lacks apk)"
|
||||
- "Use --group-add 281 to grant docker socket access to node user"
|
||||
- "Mount curl from /mnt/user/appdata/n8n/bin/ for persistence across updates"
|
||||
|
||||
patterns-established:
|
||||
- "Static binaries mounted as volumes for hardened containers"
|
||||
- "Group-add for socket permissions in rootless containers"
|
||||
|
||||
duration: ~45min
|
||||
completed: 2026-01-29
|
||||
---
|
||||
|
||||
# Phase 2 Plan 01: Docker Socket Configuration Summary
|
||||
|
||||
**n8n container configured with Docker socket access via mounted static curl binary and group permissions**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** ~45 min (interactive configuration)
|
||||
- **Started:** 2026-01-29T13:45:00Z
|
||||
- **Completed:** 2026-01-29T14:30:00Z
|
||||
- **Tasks:** 3
|
||||
- **Files modified:** 0 (container configuration only)
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- Docker socket mounted at `/var/run/docker.sock` in n8n container
|
||||
- Static curl binary with Unix socket support mounted at `/usr/local/bin/curl`
|
||||
- Execute Command node enabled via `NODES_EXCLUDE=` environment variable
|
||||
- Docker group (281) added to container for socket permissions
|
||||
- Verified: n8n can query Docker API and retrieve container list
|
||||
|
||||
## Task Commits
|
||||
|
||||
This plan involved container configuration only - no code changes to commit.
|
||||
|
||||
**Configuration changes applied:**
|
||||
1. Volume mount: `/var/run/docker.sock` → `/var/run/docker.sock`
|
||||
2. Volume mount: `/mnt/user/appdata/n8n/bin/curl` → `/usr/local/bin/curl`
|
||||
3. Environment variable: `NODES_EXCLUDE=`
|
||||
4. Extra parameter: `--group-add 281`
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
No files in repository - all changes were to n8n container configuration in Unraid.
|
||||
|
||||
**On Unraid host:**
|
||||
- `/mnt/user/appdata/n8n/bin/curl` - Static curl binary downloaded
|
||||
|
||||
## Decisions Made
|
||||
|
||||
| Decision | Rationale |
|
||||
|----------|-----------|
|
||||
| Use static curl binary | Hardened n8n image lacks package manager (apk removed) |
|
||||
| Mount curl as volume | Persists across container updates unlike in-container installs |
|
||||
| Use moparisthebest static-curl | Includes Unix socket support, fully static linked |
|
||||
| Add --group-add 281 | Grants docker group access to node user for socket permissions |
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Discovery: Hardened Image Limitations
|
||||
|
||||
- **Found during:** Task 1 (curl installation)
|
||||
- **Issue:** n8n hardened image from Docker has no package manager - `apk` command not found
|
||||
- **Resolution:** Downloaded static curl binary and mounted as volume
|
||||
- **Impact:** More sustainable solution - survives container updates
|
||||
|
||||
### Discovery: Dynamic Library Dependencies
|
||||
|
||||
- **Found during:** Task 1 (curl installation)
|
||||
- **Issue:** Host's `/usr/bin/curl` couldn't be mounted - depends on shared libraries not in container
|
||||
- **Resolution:** Used fully static curl binary from moparisthebest/static-curl
|
||||
|
||||
### Discovery: Socket Permissions
|
||||
|
||||
- **Found during:** Task 2 (Docker API verification)
|
||||
- **Issue:** n8n runs as `node` user (uid=1000) but docker socket owned by group 281
|
||||
- **Resolution:** Added `--group-add 281` to container extra parameters
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 3 discoveries, all resolved
|
||||
**Impact on plan:** Approach adapted for hardened image constraints. Final solution more robust than original plan.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
- Initial curl binary lacked Unix socket support (wrong build) - resolved by using correct static build
|
||||
- Trailing space in docker.sock path from Unraid UI - resolved by manual re-entry
|
||||
- Spurious `docker.sock ` directory created - cleaned up with rmdir
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None - all configuration completed during execution.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- Docker socket access fully working
|
||||
- curl can query Docker API from within n8n container
|
||||
- Ready for Plan 02-02: Docker query workflow implementation
|
||||
|
||||
---
|
||||
*Phase: 02-docker-integration*
|
||||
*Completed: 2026-01-29*
|
||||
Reference in New Issue
Block a user