Microsoft-Rewards-Script/docs/update.md

🔄 Auto-Update System

🚀 Automatic updates to keep your installation current
Set it and forget it

---

🎯 What is Auto-Update?

The automatic update system runs after script completion to keep your installation current with the latest features, bug fixes, and security patches.

Key Features

• 🔄 Automatic updates — Runs after each script completion
• 🛡️ Safe by design — Fast-forward only Git updates
• 🐳 Docker support — Container image updates
• 🛠️ Custom scripts — Extensible update process
• 🔒 Error resilient — Failed updates don't break main script

---

⚙️ Configuration

Basic Setup

{
  "update": {
    "git": true,
    "docker": false,
    "scriptPath": "setup/update/update.mjs"
  }
}

Configuration Options

Setting	Description	Default
git	Enable Git-based updates	true
docker	Enable Docker container updates	false
scriptPath	Path to custom update script	"setup/update/update.mjs"

---

🚀 Update Methods

Git Updates (git: true)

What It Does

• 📥 Fetches latest changes from remote repository
• ⚡ Fast-forward only pulls (safe updates)
• 📦 Reinstalls dependencies (npm ci)
• 🔨 Rebuilds the project (npm run build)

Requirements

• ✅ Git installed and available in PATH
• ✅ Repository is a Git clone (not downloaded ZIP)
• ✅ No uncommitted local changes
• ✅ Internet connectivity

Process

git fetch --all --prune
git pull --ff-only
npm ci
npm run build

Docker Updates (docker: true)

What It Does

• 📥 Pulls latest container images
• 🔄 Restarts services with new images
• 💾 Preserves configurations and mounted volumes

Requirements

• ✅ Docker and Docker Compose installed
• ✅ docker-compose.yml file present
• ✅ Proper container registry access

Process

docker compose pull
docker compose up -d

---

🛠️ Custom Update Scripts

Default Script

• Path — setup/update/update.mjs
• Format — ES modules
• Arguments — Command line flags

Script Arguments

• --git — Enable Git update process
• --docker — Enable Docker update process
• Both flags can be combined

Custom Script Example

// custom-update.mjs
import { execSync } from 'child_process'

const args = process.argv.slice(2)

if (args.includes('--git')) {
  console.log('🔄 Running custom Git update...')
  execSync('git pull && npm install', { stdio: 'inherit' })
}

if (args.includes('--docker')) {
  console.log('🐳 Running custom Docker update...')
  execSync('docker-compose pull && docker-compose up -d', { stdio: 'inherit' })
}

---

⏰ Execution Timing

When Updates Run

Scenario	Update Runs
Normal completion	✅ All accounts processed successfully
Error completion	✅ Script finished with errors but completed
Interruption	❌ Script killed or crashed mid-execution

Update Sequence

1. 🏁 Main script completion — All accounts processed
2. 📊 Conclusion webhook sent (if enabled)
3. 🚀 Update process begins
4. 📥 Git updates (if enabled)
5. 🐳 Docker updates (if enabled)
6. 🔚 Process exits

---

🛡️ Safety Features

Git Safety

• ⚡ Fast-forward only — Prevents overwriting local changes
• 📦 Dependency verification — Ensures npm ci succeeds
• 🔨 Build validation — Confirms TypeScript compilation works

Error Handling

• ✅ Update failures don't break main script
• 🔇 Silent failures — Errors logged but don't crash process
• 🔄 Rollback protection — Failed updates don't affect current installation

Concurrent Execution

• 🔒 Single update process — Multiple instances don't conflict
• 🚫 Lock-free design — No file locking needed
• 🎯 Independent updates — Each script copy updates separately

---

📊 Monitoring Updates

Log Output

[UPDATE] Starting post-run update process
[UPDATE] Git update enabled, Docker update disabled
[UPDATE] Running: git fetch --all --prune
[UPDATE] Running: git pull --ff-only
[UPDATE] Running: npm ci
[UPDATE] Running: npm run build
[UPDATE] Update completed successfully

Update Verification

# Check if updates are pending
git status

# View recent commits
git log --oneline -5

# Verify build status
npm run build

---

📋 Use Cases

Development Environment

Benefit	Description
Synchronized	Keep local installation current with repository
Automated	Automatic dependency updates
Seamless	Integration of bug fixes and features

Production Deployment

Benefit	Description
Security	Automated security patches
Features	Updates without manual intervention
Consistent	Same update process across servers

Docker Environments

Benefit	Description
Images	Container image updates
Security	Patches in base images
Automated	Service restarts

---

📋 Best Practices

Git Configuration

• 🧹 Clean working directory — Commit or stash local changes
• 🌿 Stable branch — Use main or stable for auto-updates
• 📝 Regular commits — Keep repository history clean
• 💾 Backup data — Sessions and accounts before updates

Docker Configuration

• 🏷️ Image tagging — Use specific tags, not latest for production
• 💾 Volume persistence — Ensure data volumes are mounted
• 🔗 Service dependencies — Configure proper startup order
• 🎯 Resource limits — Set appropriate memory and CPU limits

Monitoring

• 📝 Check logs regularly — Monitor update success/failure
• 🧪 Test after updates — Verify script functionality
• 💾 Backup configurations — Preserve working setups
• 📊 Version tracking — Record successful versions

---

🛠️ Troubleshooting

Git Issues

Error	Solution
"Not a git repository"	Clone repository instead of downloading ZIP
"Local changes would be overwritten"	Commit or stash local changes
"Fast-forward not possible"	Repository diverged - reset to remote state

Git Reset Command

# Reset to remote state (⚠️ loses local changes)
git fetch origin
git reset --hard origin/main

Docker Issues

Error	Solution
"Docker not found"	Install Docker and Docker Compose
"Permission denied"	Add user to docker group
"No docker-compose.yml"	Create compose file or use custom script

Docker Permission Fix

# Windows: Ensure Docker Desktop is running
# Linux: Add user to docker group
sudo usermod -aG docker $USER

Network Issues

Error	Solution
"Could not resolve host"	Check internet connectivity
"Connection timeout"	Check firewall and proxy settings

---

🔧 Manual Updates

Git Manual Update

git fetch --all --prune
git pull --ff-only
npm ci
npm run build

Docker Manual Update

docker compose pull
docker compose up -d

Dependencies Only

npm ci
npm run build

---

⚙️ Update Configuration

Complete Disable

{
  "update": {
    "git": false,
    "docker": false
  }
}

Selective Enable

{
  "update": {
    "git": true,     // Keep Git updates
    "docker": false  // Disable Docker updates
  }
}

Custom Script Path

{
  "update": {
    "git": true,
    "docker": false,
    "scriptPath": "my-custom-update.mjs"
  }
}

---

🔒 Security Considerations

Git Security

• ✅ Trusted remote — Updates pull from configured remote only
• ⚡ Fast-forward only — Prevents malicious rewrites
• 📦 NPM registry — Dependencies from official registry

Docker Security

• 🏷️ Verified images — Container images from configured registries
• ✍️ Image signatures — Verify when possible
• 🔍 Security scanning — Regular scanning of base images

Script Execution

• 👤 Same permissions — Update scripts run with same privileges
• 🚫 No escalation — No privilege escalation during updates
• 🔍 Review scripts — Custom scripts should be security reviewed

---

🎯 Environment Examples

Development

{
  "update": {
    "git": true,
    "docker": false
  }
}

Production

{
  "update": {
    "git": false,
    "docker": true
  }
}

Hybrid

{
  "update": {
    "git": true,
    "docker": true,
    "scriptPath": "setup/update/production-update.mjs"
  }
}

---

🔗 Related Guides

• Getting Started — Initial setup and configuration
• Docker — Container deployment and management
• Scheduler — Automated timing and execution
• Security — Privacy and data protection