unraid-docker-manager/.planning/phases/05-polish-deploy/05-03-PLAN.md

---
phase: 05-polish-deploy
plan: 03
type: execute
wave: 3
depends_on: [05-02]
files_modified: [README.md, n8n-workflow.json]
autonomous: false

must_haves:
  truths:
    - "README has step-by-step deployment instructions"
    - "README documents credential creation in n8n"
    - "README documents Docker socket setup for n8n container"
    - "All 6 commands tested end-to-end via Telegram"
  artifacts:
    - path: "README.md"
      provides: "Deployment guide"
      min_lines: 50
      contains: "Installation"
    - path: "n8n-workflow.json"
      provides: "Production-ready workflow"
  key_links:
    - from: "README.md"
      to: "n8n credentials"
      via: "documentation"
      pattern: "telegramAuth"
---

<objective>
Write deployment README and perform end-to-end testing of complete bot functionality.

Purpose: Enable users to deploy the bot on their own Unraid servers with clear instructions.
Output: Complete README, verified workflow, production-ready deployment package.
</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/05-polish-deploy/05-CONTEXT.md
@.planning/phases/05-polish-deploy/05-RESEARCH.md
@.planning/phases/05-polish-deploy/05-01-SUMMARY.md
@.planning/phases/05-polish-deploy/05-02-SUMMARY.md
@n8n-workflow.json
</context>

<tasks>

<task type="auto">
  <name>Task 1: Write deployment README</name>
  <files>README.md</files>
  <action>
Replace the stub README with a complete deployment guide. Per CONTEXT.md: "README only - step-by-step instructions in markdown" and "No troubleshooting section - focused on initial setup only".

Structure (following RESEARCH.md template):

# Docker Manager Bot

One-line description: Telegram bot for managing Docker containers on Unraid.

## Prerequisites

- Unraid server with Docker enabled
- n8n container running on Unraid
- Telegram Bot Token (from @BotFather)
- Your Telegram User ID (from @userinfobot)

## Installation

### 1. Configure n8n Container

Document the Docker run flags needed:
```bash
docker run -d \
  --name n8n \
  --group-add 281 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /path/to/curl:/usr/bin/curl:ro \
  n8nio/n8n
```

Explain:
- `--group-add 281` for Docker socket access
- Socket mount requirement
- Static curl binary mount (hardened n8n image)

### 2. Create n8n Credentials

**Telegram API credential:**
- Type: Telegram API
- Access Token: your bot token from @BotFather

**Telegram Auth credential:**
- Type: Header Auth (or custom)
- Field: userId = your Telegram user ID

### 3. Import Workflow

- Copy n8n-workflow.json to server
- In n8n: Workflows -> Import from File
- Map credentials when prompted

### 4. Activate Workflow

- Open workflow
- Click Active toggle
- Test with "status" message

## Usage

List the 6 commands:
- status - View all containers
- start <name> - Start container
- stop <name> - Stop container
- restart <name> - Restart container
- update <name> - Pull and recreate container
- logs <name> [lines] - View container logs

Mention persistent menu buttons available.

Per CONTEXT.md: No troubleshooting section.
  </action>
  <verify>
README exists at root.
Contains all 4 installation sections.
No troubleshooting section.
Markdown renders correctly.
  </verify>
  <done>
Complete deployment guide in README.md.
Step-by-step instructions for fresh Unraid installation.
  </done>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <name>Task 2: End-to-end testing</name>
  <what-built>
Complete Docker Manager Bot:
- Keyword routing (no Claude dependency)
- Persistent Telegram menu
- All 6 container commands
- Terse error messages
- Credential-based auth
  </what-built>
  <how-to-verify>
Test each command via Telegram bot:

1. **Menu:** Send /start or any unknown text
   - Expected: Persistent keyboard appears with 6 buttons

2. **Status:** Tap Status button or type "status"
   - Expected: List of containers with status indicators

3. **Start:** Type "start <stopped-container-name>"
   - Expected: Container starts, confirmation message

4. **Stop:** Type "stop <running-container-name>"
   - Expected: Container stops, confirmation message

5. **Restart:** Type "restart <container-name>"
   - Expected: Container restarts, confirmation message

6. **Update:** Type "update <container-name>"
   - Expected: Image pulled, container recreated (or silent if no update)

7. **Logs:** Type "logs <container-name>"
   - Expected: Last 50 log lines displayed

8. **Error handling:** Stop n8n's Docker socket access briefly
   - Expected: "Cannot connect to Docker" (not stack trace)

9. **Auth:** Message bot from different Telegram account
   - Expected: No response (silent ignore per Phase 1 decision)
  </how-to-verify>
  <resume-signal>Type "approved" if all tests pass, or describe which tests failed</resume-signal>
</task>

</tasks>

<verification>
1. README exists and has all required sections
2. All 6 commands work end-to-end
3. Persistent menu functions correctly
4. Error messages are terse
5. Unauthorized users get no response
6. Workflow exports without sensitive data
</verification>

<success_criteria>
- Fresh user can follow README to deploy bot
- All container management commands functional
- Bot ready for production use on Unraid
</success_criteria>

<output>
After completion, create `.planning/phases/05-polish-deploy/05-03-SUMMARY.md`
</output>