Files

T

Lucas Berger 07cde0490a docs: complete v1.3 project research (STACK, FEATURES, ARCHITECTURE, PITFALLS, SUMMARY)

2026-02-08 19:52:57 -05:00

16 KiB

Raw Blame History

Feature Research: Unraid Update Status Sync (v1.3)

Domain: Docker container management integration with Unraid server Researched: 2026-02-08 Confidence: MEDIUM

Context

This research focuses on v1.3 milestone: syncing update status back to Unraid after bot-initiated container updates. The bot already updates containers successfully, but Unraid's UI continues showing "update available" badges and sending false-positive notifications afterward.

Existing capabilities (v1.0-v1.2):

Container update via bot (pull image, recreate container)
"Update All :latest" batch operation
Container status display with inline keyboards
Confirmation dialogs for dangerous actions
Progress feedback during operations

New scope: Two directions for Unraid integration:

Sync-back: Clear Unraid's "update available" badge after bot updates container
Read-forward: Use Unraid's update detection data as source of truth for which containers need updates

Feature Landscape

Table Stakes (Users Expect These)

Features users assume exist when managing containers outside Unraid's UI.

Feature	Why Expected	Complexity	Notes
Clear "update available" badge after bot update	Users expect Unraid UI to reflect reality after external updates	MEDIUM	Requires writing to `/var/lib/docker/unraid-update-status.json` - known workaround for Watchtower/Portainer users
Prevent duplicate update notifications	After bot updates a container, Unraid shouldn't send false-positive Telegram notifications	MEDIUM	Same mechanism as clearing badge - update status file tracks whether updates are pending
Avoid breaking Unraid's update tracking	External tools shouldn't corrupt Unraid's internal state	LOW	Docker API operations are safe - Unraid tracks via separate metadata files
No manual "Apply Update" clicks	Point of remote management is to eliminate manual steps	HIGH	Core pain point - users want "update from bot = done" not "update from bot = still need to click in Unraid"

Differentiators (Competitive Advantage)

Features that set the bot apart from other Docker management tools.

Feature	Value Proposition	Complexity	Notes
Automatic sync after every update	Bot updates container AND clears Unraid badge in single operation - zero user intervention	MEDIUM	Requires detecting update success and writing status file atomically
Use Unraid's update detection data	If Unraid already knows which containers need updates, bot could use that source of truth instead of its own Docker image comparison	HIGH	Requires parsing Unraid's update status JSON and integrating with existing container selection/matching logic
Bidirectional status awareness	Bot shows which containers Unraid thinks need updates, not just Docker image digest comparison	MEDIUM-HIGH	Depends on reading update status file - enhances accuracy for edge cases (registry issues, multi-arch images)
Manual sync command	Users can manually trigger "sync status to Unraid" if they updated containers through another tool	LOW	Simple command that iterates running containers and updates status file

Anti-Features (Commonly Requested, Often Problematic)

Features that seem good but create problems.

Feature	Why Requested	Why Problematic	Alternative
Full Unraid API integration (authentication, template parsing)	"Properly" integrate with Unraid's web interface instead of file manipulation	Adds authentication complexity, XML parsing, API version compatibility, web session management - all for a cosmetic badge	Direct file writes are the established community workaround - simpler and more reliable
Automatic template XML regeneration	Update container templates so Unraid thinks it initiated the update	Template XML is generated by Community Applications and Docker Manager - modifying it risks breaking container configuration	Clearing update status file is sufficient - templates are source of truth for config, not update state
Sync status for ALL containers on every operation	Keep Unraid 100% in sync with Docker state at all times	Performance impact (Docker API queries for all containers on every update), unnecessary for user's pain point	Sync only the container(s) just updated by the bot - targeted and efficient
Persistent monitoring daemon	Background process that watches Docker events and updates Unraid status in real-time	Requires separate container/service, adds operational complexity, duplicates n8n's event model	On-demand sync triggered by bot operations - aligns with n8n's workflow execution model

Feature Dependencies

Clear Update Badge (sync-back)
    └──requires──> Update operation success detection (existing)
    └──requires──> File write to /var/lib/docker/unraid-update-status.json

Read Unraid Update Status (read-forward)
    └──requires──> Parse update status JSON file
    └──requires──> Container ID to name mapping (existing)
    └──enhances──> Container selection UI (show Unraid's view)

Manual Sync Command
    └──requires──> Clear Update Badge mechanism
    └──requires──> Container list enumeration (existing)

Bidirectional Status Awareness
    └──requires──> Read Unraid Update Status
    └──requires──> Clear Update Badge
    └──conflicts──> Current Docker-only update detection (source of truth ambiguity)

Dependency Notes

Clear Update Badge requires Update success detection: Already have this - n8n-update.json returns success: true, updated: true with digest comparison
Read Unraid Status enhances Container selection: Could show "(Unraid: update available)" badge in status keyboard - helps users see what Unraid sees
Bidirectional Status conflicts with Docker-only detection: Need to decide: is Unraid's update status file the source of truth, or is Docker image digest comparison? Mixing both creates confusion about "which containers need updates"

MVP Definition

Launch With (v1.3)

Minimum viable - eliminates the core pain point.

Clear update badge after bot-initiated updates - Write to /var/lib/docker/unraid-update-status.json after successful update operation
Prevent false-positive notifications - Ensure status file write happens before user sees "update complete" message
Integration with existing n8n-update.json sub-workflow - Add status sync as final step in update flow (text, inline, batch modes)

Rationale: This solves the stated pain: "after updating containers through the bot, Unraid still shows update available badges and sends false-positive Telegram notifications."

Add After Validation (v1.4+)

Features to add once core sync-back is working.

Manual sync command (/sync or /sync <container>) - Trigger when user updates via other tools (Portainer, CLI, Watchtower)
Read Unraid update status for better detection - Parse /var/lib/docker/unraid-update-status.json to see which containers Unraid thinks need updates
Show Unraid's view in status keyboard - Display "(Unraid: update ready)" badge alongside container state

Trigger: User requests ability to see "what Unraid sees" or needs to sync status after non-bot updates.

Future Consideration (v2+)

Features to defer until core functionality is proven.

Bidirectional status awareness - Use Unraid's update detection as source of truth instead of Docker digest comparison
Sync on container list view - Automatically update status file when user views container list (proactive sync)
Batch status sync - /sync all command to reconcile all containers

Why defer: Unraid's update detection has known bugs (doesn't detect external updates, false positives persist). Using it as source of truth may import those bugs. Better to prove sync-back works first, then evaluate whether read-forward adds value.

Feature Prioritization Matrix

Feature	User Value	Implementation Cost	Priority
Clear update badge after bot update	HIGH	MEDIUM	P1
Prevent false-positive notifications	HIGH	LOW	P1
Manual sync command	MEDIUM	LOW	P2
Read Unraid update status	MEDIUM	MEDIUM	P2
Show Unraid's view in UI	LOW	MEDIUM	P3
Bidirectional status (Unraid as source of truth)	MEDIUM	HIGH	P3

Priority key:

P1: Must have for v1.3 launch - solves core pain point
P2: Should have for v1.4 - adds convenience, not critical
P3: Nice to have for v2+ - explore after validating core

Implementation Notes

File Format: /var/lib/docker/unraid-update-status.json

Based on community forum discussions, this file tracks update status per container. When Unraid checks for updates, it compares registry manifests and writes results here. To clear the badge, remove the container's entry from this JSON.

Example structure (inferred from community discussions):

{
  "containerId1": { "status": "update_available", "checked": "timestamp" },
  "containerId2": { "status": "up_to_date", "checked": "timestamp" }
}

Operation: After bot updates a container successfully:

Read existing JSON file
Remove entry for updated container (or set status to "up_to_date")
Write JSON back atomically

Confidence: LOW - exact format not documented officially, needs verification by reading actual file.

Integration Points

Existing bot architecture:

n8n-update.json sub-workflow already returns success: true, updated: true, oldDigest, newDigest on successful update
Three callers: Execute Text Update, Execute Callback Update, Execute Batch Update
All three modes need status sync (text, inline keyboard, batch operations)

New node requirements:

Read Update Status File (HTTP Request or Execute Command node - read JSON file)
Parse Update Status (Code node - JSON manipulation)
Write Update Status File (HTTP Request or Execute Command node - write JSON file)
Update n8n-update.json to call status sync before returning success

File access: n8n runs in Docker container, needs volume mount or HTTP access to Unraid filesystem. Docker socket proxy already provides access - may need to add file system access or use Unraid API.

Update Status Sync Mechanism

Current state: Unraid checks for updates by comparing local image digest with registry manifest digest. Results stored in /var/lib/docker/unraid-update-status.json. When container is updated externally (bot, Watchtower, CLI), Unraid doesn't re-check - status file shows stale "update available" until manually cleared.

Community workaround: Delete /var/lib/docker/unraid-update-status.json to force complete reset, OR edit JSON to remove specific container entry.

Bot approach: After successful update (pull + recreate), programmatically edit JSON file to mark container as up-to-date. This is what Unraid would do if it had performed the update itself.

Alternatives considered:

Call Unraid's "Check for Updates" API endpoint - requires authentication, web session, not documented
Trigger Unraid's update check via CLI - no known CLI command for this
Reboot server - clears status (per forum posts) but obviously unacceptable
Edit XML templates - risky, templates are config source of truth

Selected approach: Direct JSON file edit (community-proven workaround, lowest risk).

Competitor Analysis

Watchtower

Automatically updates containers on schedule
Does NOT sync status back to Unraid
Community complaint: "Watchtower running on unraid but containers still say update after it runs"
Workaround: Manual deletion of update status file

Portainer

UI-based container management
Shows its own "update available" indicator (independent of Unraid)
Does NOT sync with Unraid's update tracking
Users run both Portainer and Unraid UI, see conflicting status

Unraid Docker Compose Manager

Manages docker-compose stacks
Known issue: "Docker tab reports updates available after even after updating stack"
No automatic sync with Unraid Docker Manager

Our Approach

Automatic sync after every bot-initiated update
Transparent to user - no manual steps after update completes
Solves pain point that all other tools ignore
Differentiator: tight integration with Unraid's native tracking system

Edge Cases & Considerations

Race Conditions

Unraid's update checker runs on schedule (user configurable)
If checker runs between bot update and status file write, may re-detect update
Mitigation: Write status file immediately after image pull, before container recreate

Multi-Arch Images

Unraid uses manifest digests for update detection
Bot uses docker inspect image ID comparison
May disagree on whether update is needed (manifest vs image layer digest)
Research needed: Does Unraid use manifest digest or image digest in status file?

Failed Updates

Bot update may fail after pulling image (recreate fails, container won't start)
Should NOT clear update badge if container is broken
Status sync must be conditional on full update success (container running)

Infrastructure Containers

Bot already excludes n8n and docker-socket-proxy from batch operations
Status sync should respect same exclusions (don't clear badge for bot's own container)

File Permissions

/var/lib/docker/ typically requires root access
n8n container may not have write permissions
Need to verify access method: direct mount, docker exec, or Unraid API

Sources

Community Forums & Issue Discussions:

Workarounds & Solutions:

Unraid API & Architecture:

Docker Digest Comparison:

Feature research for: Unraid Update Status Sync (v1.3) Researched: 2026-02-08

16 KiB Raw Blame History