docs(12): plan phase with Unraid badge research and UAT
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
@@ -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>
|
||||
|
||||
|
||||
@@ -70,62 +70,73 @@ No new libraries required. All tooling already in place.
|
||||
|
||||
### 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
|
||||
│ └── Stores local sha256 hash information
|
||||
│ └── Stores image digest comparison state
|
||||
├── "Check for Updates" button
|
||||
│ └── Queries Docker registries for new digests
|
||||
│ └── Updates unraid-update-status.json
|
||||
└── Container XML templates
|
||||
└── <Registry> element stores Docker Registry URL
|
||||
│ └── Compares running container image ID vs registry latest
|
||||
│ └── If different → shows "apply update" (even if bot already updated)
|
||||
├── "Apply Update" button
|
||||
│ └── 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
|
||||
# Option A: Delete update status file to force refresh
|
||||
rm /var/lib/docker/unraid-update-status.json
|
||||
# Unraid regenerates on next check
|
||||
**Caveat:** The bot would need network access to the Unraid web UI (port 80/443), which is separate from the Docker socket proxy.
|
||||
|
||||
# Option B: Call Unraid API (if exists)
|
||||
curl -X POST http://localhost/api/docker/check-updates
|
||||
**Pattern 2: Workaround Documentation (RECOMMENDED)**
|
||||
|
||||
# Option C: Update JSON directly
|
||||
# Read unraid-update-status.json, modify specific container entry, write back
|
||||
# RISK: Schema unknown, could break Unraid's tracking
|
||||
```
|
||||
**What:** Document the limitation honestly and explain why "Apply Update" is instant
|
||||
|
||||
**Pattern 2: Workaround Documentation**
|
||||
|
||||
**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:**
|
||||
**When to use:** Default approach — programmatic solution requires Unraid API access which adds significant complexity
|
||||
|
||||
```markdown
|
||||
## Known Limitation: Unraid Update Badges
|
||||
|
||||
When the bot updates a container, Unraid's UI may continue showing
|
||||
"update available" until you manually click "Apply Update" in the
|
||||
Unraid Docker tab. This is safe — the image is already cached, so
|
||||
Unraid will recreate the container instantly.
|
||||
After the bot updates a container, Unraid's UI may show "apply update"
|
||||
on the next update check. This is expected — Unraid tracks container
|
||||
updates through its own template system, which the bot bypasses.
|
||||
|
||||
**Why this happens:** Unraid tracks updates separately from Docker
|
||||
image digests. The bot pulls the image correctly, but Unraid's
|
||||
tracking file isn't notified.
|
||||
**Why this happens:** The bot uses the Docker API directly to pull images
|
||||
and recreate containers. Unraid doesn't know the container was updated
|
||||
because it wasn't done through Unraid's template system.
|
||||
|
||||
**Workaround:** Click "Apply Update" in Unraid UI, or click "Check
|
||||
for Updates" to refresh the status.
|
||||
**What to do:** Click "Apply Update" in Unraid's Docker tab. It completes
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user