Files

T

Lucas Berger 8d0829db50 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

2026-01-29 14:23:27 -05:00

4.3 KiB

Raw Blame History

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

phase

plan

subsystem

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:

Volume mount: /var/run/docker.sock → /var/run/docker.sock
Volume mount: /mnt/user/appdata/n8n/bin/curl → /usr/local/bin/curl
Environment variable: NODES_EXCLUDE=
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

4.3 KiB Raw Blame History