luckberg/unraid-docker-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(12): create phase plan

Browse Source
This commit is contained in:
Lucas Berger
2026-02-08 17:05:18 -05:00
parent c1d988f0e7
commit 510b7d50dc
3 changed files with 321 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.planning/phases/12-polish-audit/12-01-PLAN.md
+185
View File
@@ -0,0 +1,185 @@
---
phase: 12-polish-audit
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- DEPLOY-SUBWORKFLOWS.md
- README.md
- .planning/REQUIREMENTS.md
autonomous: false
must_haves:
truths:
- "README documents that TELEGRAM_BOT_TOKEN is stored in n8n credential and referenced via $env in HTTP Request nodes"
- "README documents that user ID is hardcoded in IF nodes with instructions to change it"
- "README documents docker-socket-proxy architecture instead of direct socket mount"
- "DEBT-02 is verified fixed (single --max-time flag) and marked complete in REQUIREMENTS.md"
- "Unraid badge limitation is either solved programmatically or documented as known limitation with workaround"
artifacts:
- path: "README.md"
provides: "Updated installation and configuration documentation"
contains: "docker-socket-proxy"
- path: "DEPLOY-SUBWORKFLOWS.md"
provides: "Unraid badge limitation documentation (if not solvable)"
contains: "Known Limitation"
- path: ".planning/REQUIREMENTS.md"
provides: "Updated requirement status for DEBT-02, ENV-01, ENV-02"
contains: "DEBT-02"
key_links:
- from: "README.md"
to: "n8n-workflow.json"
via: "installation instructions reference workflow configuration"
pattern: "IF User Authenticated|IF Callback Authenticated"
---
<objective>
Investigate Unraid update badge clearing, update environment configuration documentation, and verify DEBT-02 is resolved.
Purpose: Close out documentation requirements (ENV-01, ENV-02), verify and close DEBT-02, and either solve or document the Unraid badge persistence issue (UNR-01).
Output: Updated README.md with accurate installation/config docs, updated REQUIREMENTS.md marking DEBT-02 complete, Unraid badge solution or documented limitation.
</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/12-polish-audit/12-RESEARCH.md
@README.md
@DEPLOY-SUBWORKFLOWS.md
@.planning/REQUIREMENTS.md
</context>
<tasks>
<task type="auto">
<name>Task 1: Update README with accurate environment and architecture documentation</name>
<files>README.md, .planning/REQUIREMENTS.md</files>
<action>
Update README.md to reflect the current architecture and clarify environment configuration. The current README is outdated -- it documents direct docker.sock mounting instead of docker-socket-proxy.
**Section 1 -- Installation (replace "Configure n8n Container" section):**
Replace the docker run example and flags to document docker-socket-proxy architecture:
- n8n communicates with Docker via `docker-socket-proxy` container on `dockernet` network
- No direct docker.sock mount on n8n container
- n8n container needs `--network dockernet` and the static curl binary mount
- docker-socket-proxy container handles Docker API filtering (blocks exec, build, commit)
- Reference DEPLOYMENT_GUIDE.md for detailed setup
**Section 2 -- Telegram Configuration (replace/expand "Configure Your User ID" and "Create Telegram API Credential" sections):**
Clarify ENV-01 and ENV-02:
For TELEGRAM_BOT_TOKEN (ENV-02):
- Bot token is stored in n8n's credential manager (Settings > Credentials > Telegram API)
- HTTP Request nodes reference it via `$env.TELEGRAM_BOT_TOKEN` environment variable
- Both are needed: the credential for Telegram Trigger node, the env var for HTTP Request nodes that send messages/edit keyboards
- Document: "Set TELEGRAM_BOT_TOKEN environment variable on your n8n container to the same bot token used in the credential"
For TELEGRAM_USERID (ENV-01):
- User ID is hardcoded in two IF nodes: "IF User Authenticated" and "IF Callback Authenticated"
- No environment variable needed -- edit the workflow nodes directly
- Keep existing step-by-step instructions for changing the user ID
- Clarify: "No TELEGRAM_USERID environment variable is used. The user ID is configured directly in the workflow."
**Section 3 -- Sub-workflows:**
Add a brief note that the bot uses 7 sub-workflows that must be imported separately. Reference DEPLOY-SUBWORKFLOWS.md for details. List the files: n8n-update.json, n8n-actions.json, n8n-logs.json, n8n-batch-ui.json, n8n-status.json, n8n-confirmation.json, n8n-matching.json.
**Section 4 -- Commands table:**
Add missing commands to the usage table:
- `update all` -- Update all containers with :latest tag
- `/list` -- Alias for status command
- Inline keyboard -- mention "Use /status to access the interactive container list with action buttons"
**DEBT-02 verification and closure:**
In .planning/REQUIREMENTS.md, verify and update DEBT-02:
- Grep confirmed only ONE `--max-time 600` flag exists in n8n-update.json line 137
- No duplicate flags found in any n8n-*.json file
- Mark DEBT-02 as complete with note: "Verified -- single --max-time 600 flag, no duplicates found"
- Also mark ENV-01 and ENV-02 as complete after README update
- Update the traceability table status for DEBT-02, ENV-01, ENV-02
</action>
<verify>
1. `grep -c "docker-socket-proxy" README.md` returns at least 1
2. `grep -c "TELEGRAM_BOT_TOKEN" README.md` returns at least 1
3. `grep -c "IF User Authenticated" README.md` returns at least 1
4. `grep -c "update all" README.md` returns at least 1
5. `grep "DEBT-02" .planning/REQUIREMENTS.md` shows completed status
6. `grep "ENV-01" .planning/REQUIREMENTS.md` shows completed status
</verify>
<done>
README documents docker-socket-proxy architecture (not direct socket mount), clarifies TELEGRAM_BOT_TOKEN is both n8n credential AND env var, clarifies user ID is hardcoded in IF nodes (no env var), lists all commands including "update all" and /list. DEBT-02 marked complete in REQUIREMENTS.md. ENV-01 and ENV-02 marked complete.
</done>
</task>
<task type="checkpoint:human-verify" gate="blocking">
<name>Task 2: Investigate Unraid update badge clearing on live server</name>
<files>DEPLOY-SUBWORKFLOWS.md</files>
<action>
Before presenting the checkpoint, Claude will add a "Known Limitations" section to DEPLOY-SUBWORKFLOWS.md documenting the Unraid update badge issue and preparing investigation commands.
The checkpoint asks the user to run investigation commands on their Unraid server to determine if the update badge can be cleared programmatically. Based on findings, Claude will either implement a solution or finalize the limitation documentation.
</action>
<verify>
User runs investigation commands on Unraid server and reports findings:
**Investigation commands to run on Unraid terminal/SSH:**
```bash
# 1. Check if the update status file exists and examine its structure
cat /var/lib/docker/unraid-update-status.json 2>/dev/null | python3 -c "import json,sys; d=json.load(sys.stdin); print(json.dumps(d, indent=2))" 2>/dev/null || echo "File not found or not JSON"
# 2. Check for Unraid's dockerupdate.php or similar scripts
find /usr/local/emhttp/plugins/dynamix.docker.manager -name "*.php" -exec grep -l "update" {} \; 2>/dev/null
# 3. Check if Unraid has a web API endpoint for docker updates
ls /usr/local/emhttp/plugins/dynamix.docker.manager/include/ 2>/dev/null
# 4. Check Unraid's Docker management scripts
grep -r "update" /usr/local/emhttp/plugins/dynamix.docker.manager/include/ 2>/dev/null | head -30
```
**What to report back:**
- Contents of unraid-update-status.json (or that it doesn't exist)
- Any PHP scripts or API endpoints found for update management
- Any clues about how Unraid tracks update state
Based on findings, Claude will either:
- **If programmatic solution found:** Implement badge clearing in n8n-update.json
- **If no solution found:** Finalize limitation documentation in DEPLOY-SUBWORKFLOWS.md with workaround ("Apply Update" in Unraid is instant since image is already cached)
</verify>
<done>
Unraid badge clearing is either implemented programmatically or documented as a known limitation with clear workaround instructions. UNR-01 requirement resolved.
</done>
</task>
</tasks>
<verification>
- README.md accurately reflects current architecture (docker-socket-proxy, not direct socket)
- README.md clearly documents TELEGRAM_BOT_TOKEN and user ID configuration
- REQUIREMENTS.md has DEBT-02, ENV-01, ENV-02 marked complete
- Unraid badge clearing either implemented or documented as known limitation
</verification>
<success_criteria>
- README installation instructions match actual docker-socket-proxy architecture
- ENV-01 satisfied: Documentation clarifies user ID is hardcoded, no env var needed
- ENV-02 satisfied: Documentation clarifies bot token needs both n8n credential AND env var
- DEBT-02 satisfied: Verified single --max-time flag, marked complete
- UNR-01: Either programmatic solution deployed OR limitation documented with workaround
</success_criteria>
<output>
After completion, create `.planning/phases/12-polish-audit/12-01-SUMMARY.md`
</output>
.planning/phases/12-polish-audit/12-02-PLAN.md
+131
View File
@@ -0,0 +1,131 @@
---
phase: 12-polish-audit
plan: 02
type: execute
wave: 1
depends_on: []
files_modified: []
autonomous: false
must_haves:
truths:
- "User can type 'update all' and see confirmation listing :latest containers"
- "User can tap 'Update All :latest' button in container list keyboard and see confirmation"
- "Confirming update-all triggers batch execution with progress updates"
- "Final summary shows success/failure counts for updated containers"
artifacts: []
key_links:
- from: "Keyword Router"
to: "Get All Containers For Update All"
via: "update all text command routing"
pattern: "update all"
- from: "Route Callback [updateallstart]"
to: "Answer Update All Start"
via: "uall:start callback routing"
pattern: "updateallstart"
---
<objective>
Execute deferred Phase 11 UAT tests for Update All functionality (BATCH-04 text command, BATCH-05 inline keyboard button).
Purpose: Complete the two UAT tests deferred from Phase 11. Code is already deployed -- this is validation only.
Output: UAT results confirming Update All works end-to-end via both entry points.
</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/11-update-all-callback-limits/11-02-SUMMARY.md
@.planning/phases/11-update-all-callback-limits/11-VERIFICATION.md
</context>
<tasks>
<task type="checkpoint:human-verify" gate="blocking">
<name>Task 1: UAT -- Update All via text command (BATCH-04)</name>
<files>n8n-workflow.json</files>
<action>
User verifies the Update All text command end-to-end. This was deployed in Phase 11 (Plan 11-02) but UAT was deferred. The Keyword Router matches "update all" and routes to Get All Containers For Update All, which filters :latest containers and shows a confirmation dialog. No code changes needed -- this is validation only.
</action>
<verify>
**Preconditions:**
- Workflow is active and deployed
- You have containers with :latest tag on your Unraid server
**Test Steps:**
1. Send "update all" to the bot via Telegram
2. **Expected:** Bot responds with a confirmation message listing all containers with :latest tag and their current status
3. Verify the container count in the confirmation matches your actual :latest container count
4. Tap the "Confirm" button
5. **Expected:** Progress message appears showing batch execution starting
6. Wait for execution to complete
7. **Expected:** Final summary message shows N succeeded, M failed (ideally 0 failed)
8. Send "/status" to verify containers show updated status
**Pass criteria:**
- Confirmation lists all :latest containers
- Progress updates appear during batch execution
- Summary shows accurate success/failure counts
- No error messages or timeouts
</verify>
<done>
User confirms "update all" text command triggers confirmation dialog, batch execution with progress, and summary. BATCH-04 UAT complete.
</done>
</task>
<task type="checkpoint:human-verify" gate="blocking">
<name>Task 2: UAT -- Update All via inline keyboard (BATCH-05)</name>
<files>n8n-status.json, n8n-workflow.json</files>
<action>
User verifies the Update All inline keyboard button end-to-end. This was deployed in Phase 11 (Plan 11-02). The container list keyboard in n8n-status.json includes a "Update All :latest" button with callback data `uall:start`. When tapped, Route Callback matches `updateallstart` and routes through Answer Update All Start to the same confirmation flow as the text command. No code changes needed -- this is validation only.
</action>
<verify>
**Preconditions:**
- Same as Task 1 (workflow active, :latest containers present)
**Test Steps:**
1. Send "/status" or "/list" to the bot to display the container list keyboard
2. Locate the "Update All :latest" button in the inline keyboard (below navigation, above Select Multiple)
3. Tap the "Update All :latest" button
4. **Expected:** Bot acknowledges with "Checking for updates..." callback answer
5. **Expected:** Confirmation message appears listing all :latest containers (same as text command flow)
6. Tap "Confirm" button
7. **Expected:** Same batch execution flow as Task 1 (progress, summary)
8. Send "/status" to verify containers show updated status
**Pass criteria:**
- "Update All :latest" button visible in container list keyboard
- Tapping button shows confirmation dialog with :latest containers
- Confirmation and batch execution work identically to text command
- No error messages or timeouts
</verify>
<done>
User confirms "Update All :latest" inline keyboard button triggers same confirmation and batch execution flow as text command. BATCH-05 UAT complete.
</done>
</task>
</tasks>
<verification>
- BATCH-04 (Update All text command) passes end-to-end UAT
- BATCH-05 (Update All inline keyboard) passes end-to-end UAT
- Both entry points produce identical confirmation and execution flows
</verification>
<success_criteria>
- User successfully triggers Update All via "update all" text command with confirmation and batch execution
- User successfully triggers Update All via inline keyboard button with confirmation and batch execution
- Both Phase 11 deferred UAT tests completed with pass/fail determination
</success_criteria>
<output>
After completion, create `.planning/phases/12-polish-audit/12-02-SUMMARY.md`
</output>