pi-pm3/UPDATE_MANAGER.md

Update Manager - Technical Documentation

Overview

The Update Manager provides automatic system updates from GitHub releases, including version checking, downloading, installation, and rollback capabilities.

Architecture

Backend Components

Location: app/backend/managers/update_manager.py

Key Classes:

• UpdateManager - Core manager class
• UpdateStatus - Enum for update states
• ReleaseInfo - Data class for GitHub release information
• UpdateProgress - Data class for progress tracking

API Endpoints

Location: app/backend/api/updates.py

Endpoint	Method	Description
/api/updates/check	GET	Check for available updates
/api/updates/progress	GET	Get current update progress
/api/updates/download	POST	Download available update
/api/updates/install	POST	Install downloaded update
/api/updates/release-notes	POST	Get release notes for a version
/api/updates/current-version	GET	Get current system version

Features

1. Automatic Update Checks

Periodically checks GitHub releases API for new versions:

# Configurable check interval (default: 1 hour)
UPDATE_CHECK_INTERVAL=3600

# Checks start automatically on backend startup
update_manager = get_update_manager()
await update_manager.start_periodic_checks()

Detection Logic:

• Fetches latest release from GitHub API
• Compares semantic versions (e.g., "1.2.3")
• Handles pre-release tags
• Stores last check timestamp

2. Version Comparison

Uses semantic versioning for comparison:

def _is_newer_version(self, version1: str, version2: str) -> bool:
    # Parses versions like "1.2.3" or "v1.2.3"
    # Compares major.minor.patch components
    # Returns True if version1 > version2

Supported Formats:

• Standard: 1.2.3
• Prefixed: v1.2.3
• Pre-release: 1.2.3-beta.1 (metadata stripped for comparison)

3. Update Download

Downloads release assets with progress tracking:

async def download_update(self) -> bool:
    # Downloads to temporary directory
    # Tracks progress for UI updates
    # Verifies checksum if available
    # Cleans up on failure

Features:

• Progress tracking (0-100%)
• Checksum verification (SHA256)
• Automatic cleanup on errors
• Configurable timeout

4. Installation Process

Safe installation with backup and rollback:

async def install_update(self) -> bool:
    # 1. Backup current installation
    # 2. Extract update archive
    # 3. Run post-install script
    # 4. Rebuild PM3 client
    # 5. Update version file
    # 6. Rollback on failure

Installation Steps:

1. Create backup of /opt/dangerous-pi
2. Extract tar.gz archive to install directory
3. Execute scripts/post-install.sh if present
4. Rebuild Proxmark3 client (make clean && make)
5. Update VERSION file
6. Restore backup if any step fails

5. Update States

State Machine:

IDLE → CHECKING → AVAILABLE → DOWNLOADING → INSTALLING → COMPLETE
                       ↓              ↓             ↓
                   FAILED ←────────────┴─────────────┘

State Descriptions:

• IDLE: No update activity
• CHECKING: Querying GitHub API
• AVAILABLE: Update ready to download
• DOWNLOADING: Download in progress
• INSTALLING: Installing update
• COMPLETE: Update successfully installed
• FAILED: Error occurred (see error_message)

Frontend Integration

Updates Page

Location: app/frontend/app/routes/updates.tsx

Features:

• Current version display
• Update availability check
• Release notes viewer
• Download progress bar
• Installation status
• Error handling

UI Components:

// Current Version Card
- Version number display
- Status badge
- Last check timestamp
- "Check for Updates" button

// Update Available Card
- New version number
- Download size
- Release date
- Pre-release indicator
- Release notes (scrollable)
- Download/Install buttons
- Progress bar during download
- Installation status

// Action Messages
- Success/failure notifications
- Error details

Usage Examples

Backend API

Check for Updates:

curl http://localhost:8000/api/updates/check

Response:

{
  "update_available": true,
  "current_version": "0.1.0",
  "latest_version": "0.2.0",
  "release_date": "2024-01-15T10:30:00Z",
  "changelog": "## What's New\n- Feature 1\n- Bug fixes",
  "is_prerelease": false,
  "download_size": 5242880
}

Get Progress:

curl http://localhost:8000/api/updates/progress

Response:

{
  "status": "downloading",
  "current_version": "0.1.0",
  "available_version": "0.2.0",
  "download_progress": 45.5,
  "error_message": null,
  "last_check": "2024-01-15T12:00:00Z"
}

Download Update:

curl -X POST http://localhost:8000/api/updates/download

Install Update:

curl -X POST http://localhost:8000/api/updates/install

Frontend Usage

1. Navigate to Updates page
2. Click "Check for Updates"
3. Review release notes if update available
4. Click "Download Update"
5. Wait for download to complete
6. Click "Install Update"
7. Restart service when prompted

Implementation Details

GitHub API Integration

Uses GitHub REST API v3:

# Fetch latest release
url = f"https://api.github.com/repos/{GITHUB_REPO}/releases/latest"

# Fetch specific version
url = f"https://api.github.com/repos/{GITHUB_REPO}/releases/tags/v1.0.0"

Rate Limiting:

• Unauthenticated: 60 requests/hour
• Authenticated: 5000 requests/hour
• Consider adding GitHub token for higher limits

Release Asset Requirements:

• Must include .tar.gz file
• Optional .sha256 checksum file
• Asset naming: dangerous-pi-{version}.tar.gz

Checksum Verification

SHA256 checksum validation:

async def _verify_checksum(self, file_path: Path, expected: str) -> bool:
    sha256 = hashlib.sha256()
    with open(file_path, 'rb') as f:
        while chunk := f.read(65536):  # 64KB chunks
            sha256.update(chunk)
    return sha256.hexdigest() == expected.lower()

Backup and Rollback

Automatic backup before installation:

# Backup structure
/opt/dangerous-pi/          # Current installation
/opt/dangerous-pi-backup/   # Backup before update

# Rollback on failure
if installation_fails:
    shutil.rmtree(install_dir)
    shutil.copytree(backup_dir, install_dir)

PM3 Client Rebuild

Rebuilds Proxmark3 client after updates:

async def _rebuild_pm3_client(self):
    pm3_dir = Path("/opt/proxmark3")
    if pm3_dir.exists():
        await self._run_command(
            f"cd {pm3_dir} && make clean && make"
        )

Configuration

Environment Variables

# Version (read from VERSION file or env)
VERSION=0.1.0

# GitHub repository
GITHUB_REPO=dangerous-things/dangerous-pi

# Update check interval (seconds)
UPDATE_CHECK_INTERVAL=3600

# Optional: GitHub token for higher rate limits
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Installation Paths

/opt/dangerous-pi/          # Application directory
/opt/dangerous-pi/VERSION   # Version file
/opt/dangerous-pi/scripts/  # Install scripts
/opt/dangerous-pi-backup/   # Backup directory
/tmp/dangerous-pi-update-*/ # Temporary download directory

Security Considerations

Verification

• Checksum Validation: SHA256 verification of downloads
• HTTPS Only: All downloads over HTTPS
• Signed Releases: Consider GPG signature verification (future)

Permissions

Update operations require elevated privileges:

# Commands that need sudo:
- tar -xzf (to /opt directory)
- make (for PM3 rebuild)
- systemctl restart (for service restart)

Solution: Configure sudoers for specific commands:

www-data ALL=(ALL) NOPASSWD: /bin/tar
www-data ALL=(ALL) NOPASSWD: /usr/bin/make
www-data ALL=(ALL) NOPASSWD: /bin/systemctl restart dangerous-pi

Backup Safety

• Backup created before every installation
• Single backup retained (consider multiple backup retention)
• Automatic rollback on installation failure
• Manual rollback possible by copying backup

Troubleshooting

Update Check Fails

Symptom: "Failed to check for updates"

Check:

# Test GitHub API access
curl https://api.github.com/repos/YOUR_REPO/releases/latest

# Check network connectivity
ping api.github.com

# Verify GITHUB_REPO config
echo $GITHUB_REPO

Solutions:

• Check internet connection
• Verify repository exists and is public
• Add GitHub token if rate limited
• Check firewall settings

Download Fails

Symptom: Download stuck or fails

Check:

# Check disk space
df -h /tmp

# Check network speed
wget --spider https://github.com/releases/download/test.tar.gz

# Check download URL
curl -I [download_url]

Solutions:

• Free up disk space
• Check network connection
• Verify asset exists in release
• Increase timeout if slow connection

Installation Fails

Symptom: Installation fails, system rolled back

Check:

# Check installation directory
ls -la /opt/dangerous-pi

# Check backup exists
ls -la /opt/dangerous-pi-backup

# Check permissions
stat /opt/dangerous-pi

# Check logs
journalctl -u dangerous-pi

Solutions:

• Verify sufficient disk space
• Check directory permissions
• Ensure backup directory is not corrupted
• Run post-install script manually to debug

PM3 Rebuild Fails

Symptom: PM3 client rebuild fails during installation

Check:

# Check PM3 directory
ls -la /opt/proxmark3

# Try manual rebuild
cd /opt/proxmark3
make clean
make

# Check build dependencies
dpkg -l | grep build-essential

Solutions:

• Install missing build dependencies
• Check PM3 source integrity
• Run rebuild manually
• Skip rebuild if PM3 not used

Testing

Unit Tests

# Test version comparison
assert manager._is_newer_version("1.2.0", "1.1.0") == True
assert manager._is_newer_version("1.0.0", "1.0.0") == False
assert manager._is_newer_version("2.0.0", "1.9.9") == True

# Test checksum verification
assert await manager._verify_checksum(file_path, valid_checksum) == True
assert await manager._verify_checksum(file_path, invalid_checksum) == False

Integration Tests

# Test check endpoint
curl http://localhost:8000/api/updates/check

# Test download (requires available update)
curl -X POST http://localhost:8000/api/updates/download

# Test progress polling
while true; do
  curl http://localhost:8000/api/updates/progress
  sleep 1
done

# Test installation
curl -X POST http://localhost:8000/api/updates/install

Manual Testing

1. Fresh Check:

   • Start backend
   • Verify automatic check on startup
   • Check last_check timestamp

2. Update Flow:

   • Create new release on GitHub
   • Click "Check for Updates"
   • Verify release notes display
   • Download update
   • Monitor progress bar
   • Install update
   • Verify version changed

3. Failure Scenarios:

   • Test with no internet
   • Test with invalid checksum
   • Test with insufficient disk space
   • Verify rollback works

4. Periodic Checks:

   • Wait for automatic check (default: 1 hour)
   • Verify no UI interruption
   • Check last_check updates

Performance

Check Duration

• API request: ~200-500ms
• Version parsing: <10ms
• Total: <1 second

Download Duration

• Depends on file size and connection speed
• Example: 5MB @ 10Mbps = ~4 seconds
• Progress updates every 8KB chunk

Installation Duration

• Extract: ~5-10 seconds (5MB archive)
• PM3 rebuild: ~30-60 seconds
• Total: ~1-2 minutes

Resource Usage

• Memory: Minimal (<10MB during download)
• CPU: Low (except during PM3 rebuild)
• Disk: 2x update size (download + extracted)

Future Enhancements

Near Term

• Multiple backup retention
• Scheduled update windows
• Update notifications via SSE
• Auto-restart after installation
• Rollback UI button

Medium Term

• Delta updates (only changed files)
• Update channels (stable, beta, nightly)
• Manual update file upload
• Update history/changelog viewer
• Automatic rollback on boot failure

Long Term

• A/B partition updates
• Incremental updates
• Peer-to-peer update distribution
• OTA firmware updates for PM3
• Update signing and verification (GPG)

Code Organization

app/backend/
├── managers/
│   └── update_manager.py      # Core update logic (500+ lines)
├── api/
│   └── updates.py              # API endpoints (150 lines)
├── config.py                   # VERSION, GITHUB_REPO config
└── main.py                     # Periodic checks initialization

app/frontend/
└── app/routes/
    └── updates.tsx             # Update UI (350+ lines)

Dependencies

Python Packages:

• aiohttp - Async HTTP client for GitHub API
• hashlib - Checksum verification (built-in)
• asyncio - Async operations (built-in)

System Commands:

• tar - Archive extraction
• make - PM3 client rebuild
• systemctl - Service management (future)

Optional:

• GitHub personal access token for higher rate limits

Conclusion

The Update Manager provides a robust, automatic update system with:

• Seamless GitHub integration
• Safe installation with rollback
• Real-time progress tracking
• Version management
• Error handling and recovery

It ensures Dangerous Pi stays up-to-date with minimal user intervention while maintaining system stability through backups and automatic rollback on failure.