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/ROADMAP.md
+1 -1
View File
@@ -139,7 +139,7 @@ Plans:
- [ ] 12-02-PLAN.md — Deferred UAT: Update All text command (BATCH-04) and inline keyboard (BATCH-05) - [ ] 12-02-PLAN.md — Deferred UAT: Update All text command (BATCH-04) and inline keyboard (BATCH-05)
**Success Criteria:** **Success Criteria:**
1. After bot successfully updates a container, Unraid UI no longer shows "update available" for that container 1. Unraid update badge behavior documented as known limitation with workaround (bot bypasses Unraid template system)
2. Documentation clarifies whether TELEGRAM_USERID env var is required or can be hardcoded 2. Documentation clarifies whether TELEGRAM_USERID env var is required or can be hardcoded
3. Documentation clarifies whether TELEGRAM_BOT_TOKEN env var is required or if n8n credential suffices 3. Documentation clarifies whether TELEGRAM_BOT_TOKEN env var is required or if n8n credential suffices
4. Image pull command has single --max-time flag (600s) 4. Image pull command has single --max-time flag (600s)
.planning/phases/12-polish-audit/12-01-PLAN.md
+40 -27
View File
@@ -8,7 +8,7 @@ files_modified:
- DEPLOY-SUBWORKFLOWS.md - DEPLOY-SUBWORKFLOWS.md
- README.md - README.md
- .planning/REQUIREMENTS.md - .planning/REQUIREMENTS.md
autonomous: false autonomous: true
must_haves: must_haves:
truths: truths:
@@ -122,44 +122,57 @@ README documents docker-socket-proxy architecture (not direct socket mount), cla
</done> </done>
</task> </task>
<task type="checkpoint:human-verify" gate="blocking"> <task type="auto">
<name>Task 2: Investigate Unraid update badge clearing on live server</name> <name>Task 2: Document Unraid update badge limitation (UNR-01)</name>
<files>DEPLOY-SUBWORKFLOWS.md</files> <files>DEPLOY-SUBWORKFLOWS.md</files>
<action> <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. **Root cause (confirmed by user testing):**
</action> - The bot uses Docker API directly to pull images and recreate containers
<verify> - Unraid manages containers through its own XML template system (`/boot/config/plugins/dockerMan/templates-user/`)
User runs investigation commands on Unraid server and reports findings: - 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 ```markdown
# 1. Check if the update status file exists and examine its structure ## Known Limitations
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 ### Unraid Update Badges (UNR-01)
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 After the bot updates a container, Unraid's Docker tab may show "apply update"
ls /usr/local/emhttp/plugins/dynamix.docker.manager/include/ 2>/dev/null on the next update check. This is expected behavior.
# 4. Check Unraid's Docker management scripts **Why this happens:** The bot uses the Docker API directly to pull images and
grep -r "update" /usr/local/emhttp/plugins/dynamix.docker.manager/include/ 2>/dev/null | head -30 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:** Also update .planning/REQUIREMENTS.md to mark UNR-01 status as "Documented limitation with workaround" and update the traceability table.
- Contents of unraid-update-status.json (or that it doesn't exist) </action>
- Any PHP scripts or API endpoints found for update management <verify>
- Any clues about how Unraid tracks update state 1. `grep -c "Known Limitations" DEPLOY-SUBWORKFLOWS.md` returns at least 1
2. `grep -c "UNR-01" DEPLOY-SUBWORKFLOWS.md` returns at least 1
Based on findings, Claude will either: 3. `grep "UNR-01" .planning/REQUIREMENTS.md` shows updated status
- **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> </verify>
<done> <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> </done>
</task> </task>
.planning/phases/12-polish-audit/12-RESEARCH.md
+48 -37
View File
@@ -70,62 +70,73 @@ No new libraries required. All tooling already in place.
### Unraid Update Status Tracking ### Unraid Update Status Tracking
**Current understanding:** **UPDATED based on user testing (2026-02-08):**
User tested with code-server container. Key observations:
1. Bot pulled update for code-server that wasn't yet showing in Unraid UI
2. After clicking "Check for Updates" in Unraid, it went from "up to date" to "apply update"
3. Clicking "Apply Update" just restarted the container (image was already cached)
4. "Check for Updates" does NOT clear the badge — it actually CREATES it
**Root cause (revised):** Unraid compares the running container's image ID against the latest pulled image. When the bot pulls a new image and recreates the container via Docker API, Unraid's template system doesn't register the recreation. On next "Check for Updates", Unraid sees the new image is available and flags the container — even though the container may already be running the new image.
The issue is that Unraid manages containers through its own **XML template system** (`/boot/config/plugins/dockerMan/templates-user/`). When Unraid "applies" an update, it:
1. Removes the old container
2. Pulls the image (already cached = instant)
3. Recreates the container FROM ITS XML TEMPLATE
4. Updates its internal tracking
The bot bypasses this template system entirely — it uses Docker API directly. Unraid doesn't know the container was recreated.
``` ```
Unraid update tracking mechanism: Unraid update tracking mechanism (revised):
├── /boot/config/plugins/dockerMan/templates-user/my-*.xml
│ └── Container creation templates (ports, volumes, env vars)
├── /var/lib/docker/unraid-update-status.json ├── /var/lib/docker/unraid-update-status.json
│ └── Stores local sha256 hash information │ └── Stores image digest comparison state
├── "Check for Updates" button ├── "Check for Updates" button
│ └── Queries Docker registries for new digests │ └── Compares running container image ID vs registry latest
│ └── Updates unraid-update-status.json │ └── If different → shows "apply update" (even if bot already updated)
└── Container XML templates ├── "Apply Update" button
└── <Registry> element stores Docker Registry URL │ └── Removes container, pulls image (cached), recreates from XML template
│ └── Updates tracking state
└── Key insight: "Check for Updates" does NOT clear badges, it CREATES them
``` ```
**Pattern 1: Post-Update Notification** **Pattern 1: Update via Unraid's Template System**
**What:** After bot successfully pulls image and recreates container, trigger Unraid's update check mechanism **What:** After pulling the image, use Unraid's own update mechanism to recreate the container
**When to use:** If Unraid exposes an API endpoint or file-based trigger **When to use:** If Unraid exposes an API endpoint to apply updates
**Implementation options:** **Potential approach:** Unraid's web UI makes HTTP calls to its own emhttp backend. The "Apply Update" button likely hits an endpoint like `/plugins/dynamix.docker.manager/include/CreateDocker.php` or similar. If we can replicate that call, Unraid would properly track the update.
```bash **Caveat:** The bot would need network access to the Unraid web UI (port 80/443), which is separate from the Docker socket proxy.
# Option A: Delete update status file to force refresh
rm /var/lib/docker/unraid-update-status.json
# Unraid regenerates on next check
# Option B: Call Unraid API (if exists) **Pattern 2: Workaround Documentation (RECOMMENDED)**
curl -X POST http://localhost/api/docker/check-updates
# Option C: Update JSON directly **What:** Document the limitation honestly and explain why "Apply Update" is instant
# Read unraid-update-status.json, modify specific container entry, write back
# RISK: Schema unknown, could break Unraid's tracking
```
**Pattern 2: Workaround Documentation** **When to use:** Default approach — programmatic solution requires Unraid API access which adds significant complexity
**What:** If no programmatic solution exists, document the limitation and provide user instructions
**When to use:** If Unraid doesn't expose APIs and file manipulation is too risky
**Example documentation:**
```markdown ```markdown
## Known Limitation: Unraid Update Badges ## Known Limitation: Unraid Update Badges
When the bot updates a container, Unraid's UI may continue showing After the bot updates a container, Unraid's UI may show "apply update"
"update available" until you manually click "Apply Update" in the on the next update check. This is expected — Unraid tracks container
Unraid Docker tab. This is safe — the image is already cached, so updates through its own template system, which the bot bypasses.
Unraid will recreate the container instantly.
**Why this happens:** Unraid tracks updates separately from Docker **Why this happens:** The bot uses the Docker API directly to pull images
image digests. The bot pulls the image correctly, but Unraid's and recreate containers. Unraid doesn't know the container was updated
tracking file isn't notified. because it wasn't done through Unraid's template system.
**Workaround:** Click "Apply Update" in Unraid UI, or click "Check **What to do:** Click "Apply Update" in Unraid's Docker tab. It completes
for Updates" to refresh the status. instantly because the image is already cached — Unraid just recreates the
container from its template to sync its tracking state.
**Note:** "Check for Updates" does NOT clear the badge. It may actually
cause a badge to appear if the bot updated a container that Unraid hadn't
checked yet.
``` ```
### Environment Variable Documentation ### Environment Variable Documentation