claudetools/UPDATES_PAGE_USER_GUIDE.md

Updates Page - User Guide

Overview

The Updates page provides a centralized dashboard for managing agent version rollouts across your GuruRMM infrastructure. It shows real-time health metrics and enables safe promotion or emergency rollback of agent versions.

Accessing the Page

1. Log into GuruRMM dashboard
2. Navigate to Config > Updates in the sidebar
3. Or visit: https://rmm.azcomputerguru.com/updates

Understanding the Table

Columns

Version

• Displays the agent version number (e.g., 0.6.27)
• Shown in monospace font for clarity
• Sorted newest to oldest

OS / Arch

• Operating system and architecture
• Examples: windows / x86_64, linux / aarch64
• Each OS/arch combination is tracked separately

Channel

• Beta (blue badge): Testing channel with limited agents
• Stable (purple badge): Production channel with all agents

Health Status

• Healthy (green): All metrics within safe thresholds
• Warning (yellow): Some metrics approaching thresholds
• Critical (red): Metrics exceed safety thresholds
• Blocked (dark red): Version blocked from promotion
• Unknown (gray): No health data yet

Success Rate

• Percentage of successful update attempts
• Color coded:
  • Green: >= 95% (excellent)
  • Yellow: >= 80% (acceptable)
  • Red: < 80% (concerning)
• Shows fraction: e.g., "96% (48/50)"

Beta Agents

• Number of agents currently on this version in beta channel
• Updates in real-time

Stable Agents

• Number of agents currently on this version in stable channel
• Updates in real-time

Actions

• Promote (up arrow): Move beta version to stable
• Rollback (rotate arrow): Force downgrade all agents

Promoting a Version to Stable

When to Promote

Promote a beta version when:

• Health status is "Healthy" (green)
• Success rate is >= 95%
• Beta agents have been running it for sufficient time
• No critical issues reported

How to Promote

1. Find the beta version you want to promote
2. Click the Promote button (up arrow)
3. Review the confirmation dialog
4. Click Promote to confirm

If Health Check Fails

If the automatic health check fails (e.g., crash rate too high):

1. You'll see a warning dialog explaining the issue
2. Option to Force Promote appears
3. Review the warning carefully
4. Only force promote if you understand the risks
5. Consider investigating the health issues first

After Promotion

• Success toast shows: "Version X.Y.Z promoted to stable"
• Table refreshes automatically
• All agents on "stable" channel will update to this version
• Beta agents remain on beta (they'll get the next beta)

Rolling Back a Version

When to Rollback

Rollback a version when:

• Critical bug discovered after promotion
• Unexpected behavior in production
• Security vulnerability found
• Performance issues causing problems

How to Rollback

1. Find the version causing issues
2. Click the Rollback button (rotate arrow)
3. Enter a required reason in the dialog
   • Example: "Critical memory leak causing crashes"
   • This reason is logged for audit purposes
4. Review the warning: "This will force-downgrade all agents"
5. Click Rollback to confirm

After Rollback

• Success toast shows: "Version X.Y.Z rolled back. N agents downgraded"
• All agents on this version will downgrade immediately
• Previous stable version becomes active again
• Rollback is logged in the database

Understanding Health Metrics

What Gets Tracked

• Total Attempts: Number of agents that attempted to update
• Success Count: Updates that completed successfully
• Failure Count: Updates that failed (network, download, etc.)
• Crash Count: Agents that crashed after updating

Health Status Calculation

The system automatically calculates health based on:

• Success rate (success_count / total_attempts)
• Crash rate (crash_count / total_attempts)
• Failure patterns over time

Thresholds (from Phase 4)

• Healthy:
  • Success rate >= 95%
  • Crash rate < 1%
  • Failure rate < 5%
• Warning:
  • Success rate 90-94%
  • Crash rate 1-2%
  • Failure rate 5-10%
• Critical:
  • Success rate < 90%
  • Crash rate >= 2%
  • Failure rate > 10%
• Blocked:
  • Crash rate >= 5% (auto-blocked from promotion)

Auto-Refresh

Behavior

• Table refreshes every 30 seconds automatically
• Manual refresh available with Refresh button
• Auto-refresh doesn't interrupt dialogs or actions
• Loading indicator shows during refresh

Why Auto-Refresh?

• See real-time health status changes
• Monitor promotion rollout progress
• Catch issues as they emerge
• No need to manually reload

Best Practices

Testing Flow

1. Deploy to Beta: Build and deploy new version
2. Monitor Health: Watch Updates page for 24-48 hours
3. Check Success Rate: Ensure >= 95% success
4. Review Logs: Look for any errors or warnings
5. Promote: Once healthy, promote to stable
6. Monitor Rollout: Watch stable agents update
7. Be Ready: Keep an eye on metrics for first hour

Emergency Response

1. Notice Issue: See critical health status or reports
2. Assess Impact: Check how many agents affected
3. Rollback: Use rollback button immediately
4. Document: Provide clear reason in rollback dialog
5. Investigate: Review logs and crash reports
6. Fix: Prepare hotfix version
7. Re-test: Deploy to beta first, never skip testing

Version Naming

• Use semantic versioning: MAJOR.MINOR.PATCH
• Example: 0.6.27 → 0.6.28 (patch), 0.7.0 (minor), 1.0.0 (major)
• Consistent versioning helps with sorting and tracking

Common Scenarios

Scenario 1: Normal Promotion

1. New version 0.6.28 deployed to beta
2. 15 beta agents update successfully (100% success rate)
3. Health shows "Healthy" (green)
4. After 24 hours, promote to stable
5. 230 stable agents begin updating
6. Monitor for issues during rollout

Scenario 2: Warning Status

1. Beta version shows "Warning" (yellow)
2. Success rate is 92% (46/50 agents)
3. Investigate: 4 agents failed due to network timeout
4. Decision: Wait longer or fix issue before promoting
5. Do not promote until "Healthy"

Scenario 3: Emergency Rollback

1. Version 0.6.28 promoted to stable
2. After 30 minutes, users report crashes
3. Updates page shows "Critical" status
4. Crash count increasing
5. Immediately rollback with reason: "Crashes on startup"
6. Agents downgrade within minutes
7. Investigate crash dumps and fix issue

Scenario 4: Force Promotion

1. Beta version shows "Warning" but issue is minor
2. Attempt to promote
3. System blocks due to health check
4. Review the specific warning
5. If acceptable (e.g., known cosmetic issue), force promote
6. Monitor closely after force promotion

Troubleshooting

Table Shows "No rollouts yet"

• No versions have been deployed to beta or stable
• Build and deploy a version to see it appear
• Check server logs for build issues

Promote Button Disabled

• Version is not on beta channel (only beta can promote)
• Health status is not "Healthy"
• Hover over button to see tooltip explaining why

Auto-Refresh Stopped

• Check network connection
• Check browser console for errors
• Try manual refresh button
• Reload page if issues persist

Action Failed with Error

• Check network connectivity
• Verify you're still logged in
• Check server status
• Review error message in toast notification

Security & Permissions

Who Can Promote/Rollback?

• Currently: All authenticated users
• Future: May be restricted to admin role
• All actions are logged with user attribution

Audit Trail

• All promotions logged in database
• All rollbacks logged with reason
• Timestamps and user IDs recorded
• Review audit logs: rollout_events table

Performance

Page Load Time

• Initial load: < 2 seconds
• Auto-refresh: < 500ms
• Action response: < 1 second

Mobile Support

• Fully responsive design
• Table scrolls horizontally on small screens
• Dialogs adapt to mobile viewport
• All actions work on touch devices

Related Pages

Agent Detail Page

• Shows current version for individual agent
• Links to Updates page for version info
• Displays update channel (beta/stable)

Policies Page

• Configure auto-update policies
• Set update channel per client/site/agent
• Control update timing and windows

Logs Page

• View update-related log entries
• Filter by "update" or "rollout" keywords
• See detailed failure messages

Support

Need Help?

• Check server logs: /api/logs endpoint
• Review agent logs on affected machines
• Contact support with version number and error details
• Include rollout health metrics in report

Report Issues

• Use rollback feature to mitigate first
• Document reproduction steps
• Include success rate and crash count
• Provide sample agent IDs affected

---

Version: 1.0 Last Updated: 2026-05-25 Part of: Safe Agent Rollout System (Phase 5)