---
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*