unraid-docker-manager/.planning/phases/02-docker-integration/02-01-PLAN.md

---
phase: 02-docker-integration
plan: 01
type: execute
wave: 1
depends_on: []
files_modified: []
autonomous: false

user_setup:
  - service: unraid-docker
    why: "n8n needs Docker socket access and curl for Docker API queries"
    dashboard_config:
      - task: "Mount Docker socket to n8n container"
        location: "Unraid Docker settings for n8n container -> Add path: /var/run/docker.sock"
      - task: "Add NODES_EXCLUDE environment variable"
        location: "Unraid Docker settings for n8n container -> Add variable: NODES_EXCLUDE="
      - task: "Install curl in n8n container"
        location: "Unraid terminal: docker exec -u root n8n apk add curl"

must_haves:
  truths:
    - "Docker socket is mounted in n8n container"
    - "Execute Command node is enabled in n8n"
    - "curl is available in n8n container"
    - "n8n can query Docker API and get container list"
  artifacts:
    - path: "n8n container configuration"
      provides: "Docker socket mount at /var/run/docker.sock"
    - path: "n8n environment"
      provides: "NODES_EXCLUDE= env var enabling Execute Command"
    - path: "n8n container"
      provides: "curl binary available"
  key_links:
    - from: "n8n Execute Command node"
      to: "Docker socket"
      via: "curl --unix-socket"
      pattern: "curl.*unix-socket.*/var/run/docker.sock"
---

<objective>
Configure n8n container with Docker socket access and required tools for Docker API queries.

Purpose: Enable n8n to communicate with Docker Engine API to query container information.
Output: n8n container configured and verified to query Docker containers.
</objective>

<execution_context>
@/home/luc/.claude/get-shit-done/workflows/execute-plan.md
@/home/luc/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/02-docker-integration/02-RESEARCH.md
</context>

<tasks>

<task type="checkpoint:human-action" gate="blocking">
  <name>Task 1: Configure n8n Container for Docker Access</name>
  <action>
    User must configure n8n container in Unraid with the following:

    1. **Mount Docker socket:**
       - Unraid Docker UI -> n8n container -> Edit
       - Add path mapping: Container Path: `/var/run/docker.sock` -> Host Path: `/var/run/docker.sock`
       - Access Mode: Read/Write

    2. **Enable Execute Command node:**
       - Add environment variable: `NODES_EXCLUDE=` (empty string)
       - This re-enables the Execute Command node which is disabled by default in n8n 2.0+

    3. **Install curl in n8n container:**
       - After container restarts, run: `docker exec -u root n8n apk add curl`
       - This adds curl to the Alpine-based n8n image

    4. **Restart n8n container** to apply changes
  </action>
  <resume-signal>Confirm all three steps completed (socket mounted, env var set, curl installed)</resume-signal>
</task>

<task type="auto">
  <name>Task 2: Verify Docker API Access</name>
  <files>None (verification only)</files>
  <action>
    Create a simple verification to confirm Docker socket access works.

    The user should run this command on the Unraid server:
    ```bash
    docker exec n8n curl --unix-socket /var/run/docker.sock 'http://localhost/v1.53/containers/json?all=true'
    ```

    If successful, this returns JSON array of containers.

    Common issues:
    - "Permission denied": Socket permissions issue - may need to run n8n as root or adjust socket permissions
    - "curl: not found": curl not installed - run `docker exec -u root n8n apk add curl`
    - Empty response `[]`: Docker has no containers (unlikely on Unraid)

    Document the verification command for user to run.
  </action>
  <verify>
    User runs: `docker exec n8n curl --unix-socket /var/run/docker.sock 'http://localhost/v1.53/containers/json?all=true'`
    Expected: JSON array containing container objects with Id, Names, State, Status fields
  </verify>
  <done>Docker API returns container list via curl in n8n container</done>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <name>Task 3: Confirm Docker Access Working</name>
  <what-built>Docker socket access from n8n container via curl</what-built>
  <how-to-verify>
    Run this command on Unraid:
    ```bash
    docker exec n8n curl --unix-socket /var/run/docker.sock 'http://localhost/v1.53/containers/json?all=true'
    ```

    Expected result:
    - JSON array with your containers
    - Each container has: Id, Names (with leading slash), State, Status
    - Example: `[{"Id":"abc123","Names":["/plex-server"],"State":"running","Status":"Up 2 days"...}]`

    If you see the JSON output, Docker integration is ready.
  </how-to-verify>
  <resume-signal>Confirm JSON container list returned, or describe error</resume-signal>
</task>

</tasks>

<verification>
- Docker socket mounted at /var/run/docker.sock in n8n container
- NODES_EXCLUDE environment variable set (empty string)
- curl available in n8n container
- Docker API responds with container list via curl
</verification>

<success_criteria>
- `docker exec n8n curl --unix-socket /var/run/docker.sock 'http://localhost/v1.53/containers/json?all=true'` returns JSON container array
- n8n container has Execute Command node available in node palette
</success_criteria>

<output>
After completion, create `.planning/phases/02-docker-integration/02-01-SUMMARY.md`
</output>