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

docs(12): plan phase with Unraid badge research and UAT

Browse Source 
Research found Unraid badge issue is architectural (bot bypasses
Unraid's XML template system). Updated plans to document limitation
with workaround instead of attempting programmatic fix. Plan 01
covers docs/env/debt, Plan 02 covers deferred Update All UAT.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Lucas Berger
2026-02-08 17:09:24 -05:00
parent 510b7d50dc
commit 1ef726942a
3 changed files with 89 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.planning/phases/12-polish-audit/12-01-PLAN.md
+40 -27
View File
@@ -8,7 +8,7 @@ files_modified:
- DEPLOY-SUBWORKFLOWS.md
- README.md
- .planning/REQUIREMENTS.md
autonomous: false
autonomous: true
must_haves:
truths:
@@ -122,44 +122,57 @@ README documents docker-socket-proxy architecture (not direct socket mount), cla
</done>
</task>
<task type="checkpoint:human-verify" gate="blocking">
<name>Task 2: Investigate Unraid update badge clearing on live server</name>
<task type="auto">
<name>Task 2: Document Unraid update badge limitation (UNR-01)</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.
Document the Unraid update badge limitation as a known issue with clear explanation and workaround.
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:
**Root cause (confirmed by user testing):**
- The bot uses Docker API directly to pull images and recreate containers
- Unraid manages containers through its own XML template system (`/boot/config/plugins/dockerMan/templates-user/`)
- When Unraid checks for updates, it compares the running container's image against the registry
- Since the bot bypassed Unraid's template system, Unraid shows "apply update" even though the container may already be running the new image
- "Check for Updates" does NOT clear the badge — it actually CREATES the badge if the bot updated a container Unraid hadn't checked yet
- "Apply Update" completes instantly because the image is already cached — Unraid just recreates from its template
**Investigation commands to run on Unraid terminal/SSH:**
**Add a "Known Limitations" section to DEPLOY-SUBWORKFLOWS.md:**
```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"
```markdown
## Known Limitations
# 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
### Unraid Update Badges (UNR-01)
# 3. Check if Unraid has a web API endpoint for docker updates
ls /usr/local/emhttp/plugins/dynamix.docker.manager/include/ 2>/dev/null
After the bot updates a container, Unraid's Docker tab may show "apply update"
on the next update check. This is expected behavior.
# 4. Check Unraid's Docker management scripts
grep -r "update" /usr/local/emhttp/plugins/dynamix.docker.manager/include/ 2>/dev/null | head -30
**Why this happens:** The bot uses the Docker API directly to pull images and
recreate containers. Unraid manages containers through its own XML template
system and doesn't know the container was updated outside of its control.
**What to do:** Click "Apply Update" in Unraid's Docker tab. It completes
instantly because the image is already pulled and cached — Unraid just
recreates the container from its template to sync its internal tracking.
**Important:** "Check for Updates" in Unraid does NOT clear an existing badge.
It may actually cause a new badge to appear if the bot updated a container that
Unraid hadn't checked yet.
**Why not fix programmatically:** Clearing the badge would require calling
Unraid's internal web API to "apply" the update through its template system.
This adds significant complexity (Unraid web UI access, authentication,
template parsing) for a cosmetic issue that takes one click to resolve.
```
**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)
Also update .planning/REQUIREMENTS.md to mark UNR-01 status as "Documented limitation with workaround" and update the traceability table.
</action>
<verify>
1. `grep -c "Known Limitations" DEPLOY-SUBWORKFLOWS.md` returns at least 1
2. `grep -c "UNR-01" DEPLOY-SUBWORKFLOWS.md` returns at least 1
3. `grep "UNR-01" .planning/REQUIREMENTS.md` shows updated status
</verify>
<done>
Unraid badge clearing is either implemented programmatically or documented as a known limitation with clear workaround instructions. UNR-01 requirement resolved.
Unraid update badge limitation documented in DEPLOY-SUBWORKFLOWS.md with root cause explanation and workaround. UNR-01 marked as resolved (documented limitation) in REQUIREMENTS.md.
</done>
</task>