Pup Upgrades

[elusiveshiba]

Improvement Suggestion

Pup Upgrades

MVP Objective

When a Pup author publishes an update to a Pup, Dogebox should:

• Indicate to the user a Pup update is available

• Allow the user to view Pup update details and select target version

• Process updates when requested

Currently there is no automatic checking for pup updates and if a user manually updates a pup, it must be uninstalled then reinstalled.

What's needed

• Update Detection - Dogebox should periodically (on boot and every two hours) check if any installed Pups have new versions available

• Update Notification - Show "Update Available" badge on pup cards (this UI already exists)
  Nav menu should also have some kind of notification dot with a counter that indicates if multiple Pup updates are available

• Update Information - When an update is available, show:

  • Current version and target version (defaults to latest version)

  • Limit version list to significant releases (not alpha, beta etc.)

  • Release notes for target version

  • Dropdown to select any version between current and latest (release notes etc to update acordingly)

  • Update button that triggers to update to target version

• One-Click Update - New backend action that handles a pup upgrade. Pup configuration and data should be preserved as well as the Pup's enabled/disabled state

• Update skipping - Option to skip the update (hides notifications for all updates between current and latest). skipped updates record persists on device

• Update rollback - If an update failes, the pup will be in a broken state. A rollback option should be presented to the user, this will uninstall the broken pup and reinstall the previously installed version automatically.

Pup Update diagram

flowchart TD
    Start([upgradePup API Call]) --> Validate[Validate Request<br/><i>Check target version exists</i>]
    
    Validate -->|Invalid| ErrorResponse[400 Bad Request]
    Validate -->|Valid| CreateJob[Create Job<br/><i>AddAction UpgradePup</i>]
    
    CreateJob --> JobStart[Job Started<br/><i>job:created event</i>]
    JobStart --> RecordEnabled[Record if pup was enabled<br/><i>wasEnabled = s.Enabled</i>]
    
    RecordEnabled --> CheckRunning{Pup enabled?}
    CheckRunning -->|Yes| DisablePup[Disable pup in state<br/><i>PupEnabled false</i>]
    CheckRunning -->|No| SetUpgrading
    
    DisablePup --> RebuildStop[NixOS rebuild<br/><i>Container stops</i>]
    RebuildStop --> SetUpgrading
    
    SetUpgrading[Update state to UPGRADING<br/><i>SetPupInstallation STATE_UPGRADING</i>]
    SetUpgrading -->|Error| BrokenState1[markPupBroken<br/>STATE_UPDATE_FAILED]
    SetUpgrading -->|Success| CreateSnapshot
    
    CreateSnapshot[Create snapshot for rollback<br/><i>Save version, manifest, enabled state</i>]
    CreateSnapshot -->|Log warning on error| FetchManifest
    
    FetchManifest[Fetch target version manifest<br/><i>GetSourceManifest</i>]
    FetchManifest -->|Error| BrokenManifest[markPupBroken<br/>MANIFEST_FETCH_FAILED]
    FetchManifest -->|Success| ClearCache
    
    ClearCache[Clear update cache<br/><i>Prevent stale data</i>]
    ClearCache --> DownloadNew
    
    DownloadNew[Download new version<br/><i>DownloadPup - overwrites directory</i>]
    DownloadNew -->|Error| BrokenDownload[markPupBroken<br/>DOWNLOAD_FAILED]
    DownloadNew -->|Success| LoadManifest
    
    LoadManifest[Load new manifest<br/><i>LoadManifestFromPath</i>]
    LoadManifest -->|Error| BrokenLoad[markPupBroken<br/>MANIFEST_LOAD_FAILED]
    LoadManifest -->|Success| VerifyNix
    
    VerifyNix[Verify nix file hash<br/><i>SHA256 comparison</i>]
    VerifyNix -->|Hash mismatch & not dev mode| BrokenHash[markPupBroken<br/>NIX_HASH_MISMATCH]
    VerifyNix -->|Success or dev mode| UpdateState
    
    UpdateState[Update pup state<br/><i>SetPupVersion, SetPupManifest</i>]
    UpdateState -->|Error| BrokenState2[markPupBroken<br/>STATE_UPDATE_FAILED]
    UpdateState -->|Success| WriteConfig
    
    WriteConfig[Write config to storage<br/><i>WritePupConfigToStorage</i>]
    WriteConfig -->|Error| BrokenStorage[markPupBroken<br/>STORAGE_WRITE_FAILED]
    WriteConfig -->|Success| RebuildWithDisabled
    
    RebuildWithDisabled[Rebuild with Enabled=false<br/><i>WritePupFile, UpdateIncludesFile</i>]
    RebuildWithDisabled --> ApplyDisabled[Apply nix patch<br/><i>Ensures container stopped</i>]
    ApplyDisabled -->|Error| BrokenNix1[markPupBroken<br/>NIX_APPLY_FAILED]
    ApplyDisabled -->|Success| RemovePup
    
    RemovePup[Remove from NixOS config<br/><i>RemovePupFile</i>]
    RemovePup --> RebuildRemove[NixOS rebuild<br/><i>Container removed from config</i>]
    RebuildRemove -->|Error| BrokenNix2[markPupBroken<br/>NIX_APPLY_FAILED]
    RebuildRemove -->|Success| CleanDir
    
    CleanDir[Clean container directory<br/><i>rm -rf /var/lib/nixos-containers/pup-xxx</i>]
    CleanDir --> MarkReady[Mark as STATE_READY<br/><i>SetPupInstallation STATE_READY</i>]
    
    MarkReady -->|Error| BrokenState3[markPupBroken<br/>STATE_UPDATE_FAILED]
    MarkReady -->|Success| CheckWasEnabled
    
    CheckWasEnabled{Was pup enabled<br/>before upgrade?}
    CheckWasEnabled -->|No| CheckUpdates
    CheckWasEnabled -->|Yes| ReEnableState
    
    ReEnableState[Set Enabled=true in state<br/><i>PupEnabled true</i>]
    ReEnableState --> AddBack[Add pup back to config<br/><i>WritePupFile, UpdateIncludesFile</i>]
    
    AddBack --> RebuildNew[NixOS rebuild<br/><i>Treats as NEW container</i>]
    RebuildNew -->|Error| BrokenNix3[markPupBroken<br/>NIX_APPLY_FAILED]
    RebuildNew -->|Success| WaitStart
    
    WaitStart[Wait for container start<br/><i>Poll systemctl is-active</i>]
    WaitStart -->|Timeout| LogWarning[Log detailed error<br/><i>systemctl status, journalctl</i>]
    WaitStart -->|Success| CheckUpdates
    LogWarning --> CheckUpdates
    
    CheckUpdates[Background: Check for updates<br/><i>Async update check</i>]
    CheckUpdates --> EmitEvent[Emit pup-updates-checked<br/><i>Frontend refreshes cache</i>]
    EmitEvent --> CompleteJob[Complete Job<br/><i>job:completed event</i>]
    CompleteJob --> Success
    
    Success([Upgrade Complete])
    
    BrokenState1 --> Failed
    BrokenManifest --> Failed
    BrokenDownload --> Failed
    BrokenLoad --> Failed
    BrokenHash --> Failed
    BrokenState2 --> Failed
    BrokenStorage --> Failed
    BrokenNix1 --> Failed
    BrokenNix2 --> Failed
    BrokenState3 --> Failed
    BrokenNix3 --> Failed
    Failed([Failed - Rollback Available])
    
    style Start fill:#4ade80,stroke:#22c55e,color:#000
    style Success fill:#4ade80,stroke:#22c55e,color:#000
    style Failed fill:#f87171,stroke:#ef4444,color:#000
    style BrokenState1 fill:#fca5a5,stroke:#ef4444
    style BrokenManifest fill:#fca5a5,stroke:#ef4444
    style BrokenDownload fill:#fca5a5,stroke:#ef4444
    style BrokenLoad fill:#fca5a5,stroke:#ef4444
    style BrokenHash fill:#fca5a5,stroke:#ef4444
    style BrokenState2 fill:#fca5a5,stroke:#ef4444
    style BrokenStorage fill:#fca5a5,stroke:#ef4444
    style BrokenNix1 fill:#fca5a5,stroke:#ef4444
    style BrokenNix2 fill:#fca5a5,stroke:#ef4444
    style BrokenState3 fill:#fca5a5,stroke:#ef4444
    style BrokenNix3 fill:#fca5a5,stroke:#ef4444
    style CreateSnapshot fill:#fef08a,stroke:#eab308
    style CleanDir fill:#fef08a,stroke:#eab308
    style RemovePup fill:#fef08a,stroke:#eab308
    style AddBack fill:#93c5fd,stroke:#3b82f6
    style RebuildNew fill:#93c5fd,stroke:#3b82f6

Loading

Key Process Steps

Step	Description	On Error
1. Validate request	Check target version exists in available versions	400 Bad Request
2. Create job	Job tracking with WebSocket events	-
3. Record enabled state	Save wasEnabled for later re-enablement	-
4. Disable pup	Set Enabled=false, NixOS rebuild stops container	-
5. Set UPGRADING state	Mark pup as being upgraded	BROKEN
6. Create snapshot	For potential rollback	Non-fatal warning
7. Fetch manifest	Get manifest for target version	BROKEN
8. Clear cache	Prevent stale update data	-
9. Download new version	Overwrites existing pup directory	BROKEN
10. Load manifest	Parse new manifest.json	BROKEN
11. Verify nix hash	SHA256 check (skip in dev mode)	BROKEN
12. Update pup state	Apply new version/manifest	BROKEN
13. Write config	Persist to storage	BROKEN
14. Rebuild with disabled	Write pup file + includes, NixOS rebuild	BROKEN
15. Remove from config	RemovePupFile, NixOS rebuild	BROKEN
16. Clean directory	Delete container directory	-
17. Mark READY	Final state update	BROKEN
18. Re-enable	If was enabled: Set Enabled=true	-
19. Add back to config	WritePupFile + UpdateIncludesFile	BROKEN
20. Rebuild as new	NixOS treats as NEW container, autoStart triggers	BROKEN
21. Wait for start	Poll systemctl is-active with timeout	Non-fatal warning
22. Check for updates	Background check after completion	-
23. Emit event	pup-updates-checked event to frontend	-
24. Complete job	job:completed event	-

Later Objectives

• Automatic Updates - User can allow the system to automatically update specific pups or all pups to the latest versions as they're released
• Developer version - A configuration that allows alpha, beta etc. versions to be included in the version list
• Dependency conflict warnings - Warn user if dependency issues will arise due to update (eg. New Core update changes RPC, Gigawallet will be affected). Option to proceed regardless
• Update all - Option to accept all current available updates in one click

Screenshots

Update available badge on 'Installed pups' page

Update available badge on 'Installed pups' page

Update modal

Install specific version

It will be handy during testing to install specific pup versions, so that will be added

[elusiveshiba]

Discussed this yesterday and have made the following updates:

• Automatic updates moved to a later objective
• Clarified what's shown in the update information screen and what options are presented to the user
• Added dependency warning
• Added update rollback
• General tidy up

FYI @patowens @SomeoneWeird @DivineGod @stephenquoll

[elusiveshiba]

PRs:

Frontend - Dogebox-WG/dpanel#159
Backend - Dogebox-WG/dogeboxd#156