Lucas Berger
8d0829db50
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
130 lines
4.3 KiB
Markdown
130 lines
4.3 KiB
Markdown
---
|
|
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*
|