Skip to content

UPDATE.md

Latest commit

 

History

History
811 lines (604 loc) · 26.3 KB

UPDATE.md

File metadata and controls

811 lines (604 loc) · 26.3 KB
Raw

Update Guide

OpenVox GUI Version 3.10.6

This guide explains how to update your existing OpenVox GUI installation to the latest version. Updates bring new features, bug fixes, and security improvements.

Table of Contents

  1. Before You Update
  2. Quick Update (Recommended)
  3. Manual Update Process
  4. Update Scripts
  5. Rollback Process
  6. Troubleshooting Updates
  7. Version History

Before You Update

The ovox CLI is Updated Automatically

ovox is a first-class subsystem with its own ovox/VERSION file. When you run update_local.sh or deploy.sh, the CLI is refreshed along with the rest of the application.

After an update, verify with:

ovox --version

See the full ovox documentation for details on its independent versioning.

Important Preparation Steps

Think of updating like changing the oil in your car - you want to prepare first:

  1. Check Your Current Version

    # Look at the bottom-left of the web interface
# OR run this command:
curl -k https://localhost:4567/health

  2. Read the Release Notes

    • Check what's new in the version you're updating to
    • Look for any breaking changes or special instructions
    • See the Changelog for details

  3. Backup Your Data (Very Important!)

    # Create a backup directory
sudo mkdir -p /backup/openvox-gui

# Backup your data and configuration
sudo cp -r /opt/openvox-gui/data /backup/openvox-gui/data-$(date +%Y%m%d)
sudo cp -r /opt/openvox-gui/config /backup/openvox-gui/config-$(date +%Y%m%d)

  4. Schedule a Maintenance Window — Automatic via Scripts (3.7.3+)

    • Updates usually take 5-10 minutes.
    • The service will be briefly unavailable to web users.
    • Notify your users if needed.
    • Automatic behavior: update_local.sh, update_remote.sh, and deploy.sh now automatically raise the maintenance flag (/opt/openvox-gui/data/maintenance.flag + rich maintenance.json) and ensure the branded static page is in place before any file overwrites or service restarts. A shell trap guarantees the flag is removed on any exit (success, failure, or interrupt). Web users see the themed "Under Maintenance" page (Formal or Casual, with OpenVox fox SVG) via Apache instead of errors or raw JSON. The maintenance/ assets are also copied on every run.
    • Manual override/control remains available: 
      ovox maintenance enable -m "Applying GUI update $(cat VERSION)" -e "20 minutes" -y
# ... perform the update ...
ovox maintenance disable
    • See maintenance/README.md for the complete program (static pages, ovox maintenance CLI commands + sub-group under infra, backend 503 middleware, Apache config example, flag locations, workflows, and troubleshooting). The scripts also ensure proper permissions for the web server user.

Special note for upgrades to 3.6.0 or later

3.6.0 introduces the OpenVox Agent Installer -- a local package mirror under /opt/openvox-pkgs/ plus PE-style curl ... | sudo bash agent install scripts served on port 8140 -- plus comprehensive security hardening (per-route role enforcement, encrypted LDAP bind password, HMAC-verified deploy webhook, JWT revocation on logout, tightened sudoers).

When you upgrade an existing installation to 3.6.0, update_local.sh will:

  1. Drop the new sync-openvox-repo.sh script and the agent installer templates into your install dir.
  2. Render install.bash and install.ps1 with your puppetserver FQDN baked in.
  3. Install the systemd timer + service (openvox-repo-sync.{timer,service}) and enable the timer for nightly auto-sync at 02:30.
  4. Drop the puppetserver static-content mount config into /etc/puppetlabs/puppetserver/conf.d/ (you'll be reminded to restart puppetserver to activate it on port 8140).
  5. Offer an interactive "Sync now?" prompt -- because the local mirror starts out empty on first upgrade. Answer y to populate it immediately; answer N (or run with --auto/--force) to leave it empty until either the GUI's "Sync now" button or the 02:30 timer.

⚠️ The first sync downloads roughly 1-2 GB and can take 15-45 minutes on a typical broadband connection. Subsequent syncs are incremental. If you skip the initial sync prompt, the agent install one-liners will return install.bash correctly but agents will fail at the package-install step until the mirror is populated.

After the upgrade, visit Infrastructure -> Agent Install in the GUI. The page now consists of:

  • One Install Commands card with five tabs: Linux, Windows, Direct URLs, Mirror Status, Sync Log -- "Sync now" button in the card header (always visible, no matter which tab is active).
  • One Pending Certificate Requests card with Sign and Reject buttons (so the whole agent bring-up workflow lives on one page -- paste the install one-liner, wait for the CSR to appear, click Sign).

The published Linux one-liner is now the bare PE-style form:

curl -k --noproxy <fqdn> https://<fqdn>:8140/packages/install.bash | sudo bash

No --server arg, no bash -s -- -- the script auto-discovers the puppetserver FQDN from the kernel's TCP state, installs the puppet CA into the agent's system trust store, sets no_proxy, and runs the package install.

See docs/INSTALLER.md for the full feature guide.

MANDATORY ACTION (only if you use the GitHub deploy webhook): 3.6.0 hardened /api/deploy/webhook to require HMAC-SHA256 signature verification. The endpoint is disabled by default after the upgrade and returns 503 until you opt in. If you have a GitHub webhook currently pointed at this endpoint, run once:

SECRET=$(openssl rand -hex 32)
echo "OPENVOX_GUI_DEPLOY_WEBHOOK_SECRET=${SECRET}" | sudo tee -a /opt/openvox-gui/config/.env
sudo systemctl restart openvox-gui
echo "Now paste this string into the GitHub webhook 'Secret' field:"
echo "${SECRET}"

If you don't use the deploy webhook, ignore -- leaving it disabled is the safer default.

Quick Update (Recommended)

This is the easiest and safest way to update. The update script handles everything for you.

Key concept: OpenVox GUI uses a clone-then-deploy architecture. Your git repository lives in a staging directory (e.g. ~/openvox-gui), and the running installation lives at /opt/openvox-gui. The install directory is not a git repo — it is a deployment target. Updates are pulled in the staging repo, then deployed to /opt.

Step 1: Go to Your Source Repository

# Go to wherever you originally cloned the repo
cd ~/openvox-gui

Step 2: Pull the Latest Code

# Get the latest version from GitHub
git pull origin main

Step 3: Run the Update Script

# Deploy the updated code to /opt/openvox-gui and restart
sudo ./scripts/update_local.sh

What the Update Script Does

The script automatically:

  1. ✅ Backs up your data and configuration from /opt/openvox-gui
  2. ✅ Deploys updated backend, frontend, and scripts from the source repo
  3. ✅ Preserves your configuration (.env, data, certs)
  4. ✅ Updates Python dependencies
  5. ✅ Rebuilds the frontend
  6. ✅ Restarts the service
  7. ✅ Verifies everything is working

Step 4: Verify the Update

# Check the new version
curl -k https://localhost:4567/health

# Should show something like:
# {"status":"ok","version":"3.10.6"}

Open your browser and refresh the page. You might need to clear your browser cache:

  • Windows/Linux: Ctrl + F5
  • Mac: Cmd + Shift + R

Manual Update Process

If the automatic update doesn't work or you prefer to do it manually, follow these steps:

Step 1: Stop the Service

# Stop OpenVox GUI
sudo systemctl stop openvox-gui

# Verify it's stopped
sudo systemctl status openvox-gui

Step 2: Backup Current Installation

# Create backup directory with timestamp
BACKUP_DIR="/backup/openvox-gui-$(date +%Y%m%d-%H%M%S)"
sudo mkdir -p $BACKUP_DIR

# Backup everything important
sudo cp -r /opt/openvox-gui/data $BACKUP_DIR/
sudo cp -r /opt/openvox-gui/config $BACKUP_DIR/
sudo cp -r /opt/openvox-gui/backend $BACKUP_DIR/
sudo cp -r /opt/openvox-gui/frontend $BACKUP_DIR/

echo "Backup created at: $BACKUP_DIR"

Step 3: Pull Latest Code and Deploy

# Go to your source repository (NOT /opt/openvox-gui)
cd ~/openvox-gui

# Fetch latest changes
git fetch origin

# Check what will change
git log HEAD..origin/main --oneline

# Pull the updates
git pull origin main

# Deploy updated files to /opt/openvox-gui
sudo rm -rf /opt/openvox-gui/backend
sudo cp -a backend /opt/openvox-gui/
sudo cp VERSION /opt/openvox-gui/
sudo rm -rf /opt/openvox-gui/frontend
sudo cp -a frontend /opt/openvox-gui/
sudo cp scripts/enc.py scripts/deploy.sh scripts/update_local.sh /opt/openvox-gui/scripts/

Step 4: Update Python Dependencies

# Update Python packages using the install dir's venv
sudo /opt/openvox-gui/venv/bin/pip install --upgrade -r /opt/openvox-gui/backend/requirements.txt

Step 5: Update the Frontend (if needed)

# Check if frontend needs rebuilding
if [ -f "frontend/dist/.build-version" ]; then
    OLD_VERSION=$(cat frontend/dist/.build-version)
    NEW_VERSION=$(cat frontend/package.json | grep version | head -1 | awk -F'"' '{print $4}')
    
    if [ "$OLD_VERSION" != "$NEW_VERSION" ]; then
        echo "Frontend needs updating..."
        cd frontend
        npm install
        npm run build
        cd ..
    fi
else
    # No version file, rebuild to be safe
    cd frontend
    npm install
    npm run build
    cd ..
fi

Step 6: Fix Permissions

# Ensure correct ownership
sudo chown -R puppet:puppet /opt/openvox-gui

Step 7: Start the Service

# Start OpenVox GUI
sudo systemctl start openvox-gui

# Check it's running
sudo systemctl status openvox-gui

# View logs to ensure no errors
sudo journalctl -u openvox-gui -n 50

Update Scripts

OpenVox GUI includes several update scripts for different scenarios:

Local Update Script

Run from your source repo to deploy updates to /opt/openvox-gui:

cd ~/openvox-gui
git pull origin main
sudo ./scripts/update_local.sh

During update, if SSL is not yet enabled, the script will prompt:

SSL is not enabled on port 4567.
  Enable SSL using Puppet certs? [y/N]:

Answering y enables HTTPS via Puppet certificates and restarts the service.

Options:

  • --skip-backup - Don't create a backup (not recommended)
  • --force - Update even if versions match

Remote Update Script

Updates OpenVox GUI on a remote server via SSH:

# Specify the target server
./scripts/update_remote.sh --host server.example.com --user jsheets --yes

# Or set defaults via environment variables
export OPENVOX_DEPLOY_HOST=server.example.com
export OPENVOX_DEPLOY_USER=admin
./scripts/update_remote.sh --yes

This is useful for updating installations from a development machine or CI pipeline. SSH key-based authentication must be configured for the target server.

Auto-Update via Cron

Set up automatic updates (use with caution). Since the update script must run from the source repo, create a small wrapper:

# Create an update wrapper script
cat > /usr/local/bin/openvox-gui-update.sh << 'EOF'
#!/bin/bash
cd /root/openvox-gui && git pull origin main && ./scripts/update_local.sh --auto
EOF
chmod +x /usr/local/bin/openvox-gui-update.sh

# Edit crontab
sudo crontab -e

# Add this line to update weekly on Sunday at 2 AM
0 2 * * 0 /usr/local/bin/openvox-gui-update.sh >> /var/log/openvox-update.log 2>&1

Branch Switching (Testing Beta Features)

OpenVox GUI supports clean switching between stable and beta branches. The update script handles everything — file deployment, Python dependencies, database migrations, frontend rebuild, service file, sudoers, and restart.

Switch to beta (3.x)

cd ~/openvox-gui
git checkout feature/bolt-dynamic-inventory
sudo ./scripts/update_local.sh --force

Revert to stable (2.x)

cd ~/openvox-gui
git checkout main
sudo ./scripts/update_local.sh --force

The --force flag ensures the deploy runs even if version numbers match between branches. The script displays a warning when it detects a branch switch:

  ⚠ Branch switch: main → feature/bolt-dynamic-inventory

What happens during a branch switch

Component Action
Backend code Completely replaced from the new branch
Frontend Completely replaced and rebuilt
Python dependencies Reinstalled from the branch's requirements.txt
Database migrations Applied (upgrade head) or reverted as needed
Branch-specific files Deployed if present, removed if absent (e.g., bolt-plugin/)
Data and config Preserved — your .env, database, and logs are never touched
Service file + sudoers Updated and reloaded automatically

Important notes

  • Data is safe: Your database, .env config, and logs are never deleted during a branch switch. The switch only replaces application code.
  • Database schema: If a beta branch adds new database columns, they are applied via Alembic migrations. Reverting to stable leaves the extra columns in place (SQLAlchemy ignores columns it doesn't know about). For a truly clean revert, run alembic downgrade 001_baseline before switching branches.
  • Use --force: Always use the --force flag when switching branches. Without it, the script may skip the deploy if the version numbers happen to match.

Rollback Process

If something goes wrong after an update, you can rollback to the previous version:

Quick Rollback

If you just updated and need to rollback immediately:

# Stop the service
sudo systemctl stop openvox-gui

# Restore your backup (created automatically by update_local.sh)
# Find the latest backup:
ls /backup/openvox-gui/

# Restore data and config from the backup
sudo cp -r /backup/openvox-gui/TIMESTAMP/data/* /opt/openvox-gui/data/
sudo cp -r /backup/openvox-gui/TIMESTAMP/config/* /opt/openvox-gui/config/

# Restart the service
sudo systemctl start openvox-gui

Rollback to Specific Version

To rollback to a specific version, revert the source repo and redeploy:

# Go to your source repo
cd ~/openvox-gui

# List available versions (tags)
git tag -l

# Checkout a specific version
git checkout v1.3.0

# Redeploy that version
sudo ./scripts/update_local.sh --force

Restore from Backup

If you have a full backup:

# Stop the service
sudo systemctl stop openvox-gui

# Move current installation aside
sudo mv /opt/openvox-gui /opt/openvox-gui.broken

# Restore from backup
sudo cp -r /backup/openvox-gui-20240115 /opt/openvox-gui

# Fix permissions
sudo chown -R puppet:puppet /opt/openvox-gui

# Start the service
sudo systemctl start openvox-gui

Troubleshooting Updates

Common Update Problems

Problem: "git pull" shows conflicts in the source repo

Solution: You have local changes in your git repo that conflict with updates:

# Go to your source repo
cd ~/openvox-gui

# See what files are changed
git status

# To keep the official version (recommended):
git reset --hard origin/main

# OR to keep your changes:
git stash
git pull
git stash pop
# Then manually resolve conflicts

Problem: Service won't start after update

Solution: Check the logs for errors:

# Check service status
sudo systemctl status openvox-gui

# View detailed logs
sudo journalctl -u openvox-gui -n 100 --no-pager

# Common fixes:
# 1. Fix permissions
sudo chown -R puppet:puppet /opt/openvox-gui

# 2. Reinstall Python dependencies
cd /opt/openvox-gui
source venv/bin/activate
pip install -r backend/requirements.txt
deactivate

# 3. Check configuration file
sudo nano /opt/openvox-gui/config/.env

Problem: Browser shows old version after update

Solution: Clear your browser cache:

  1. Force refresh the page:

    • Windows/Linux: Ctrl + F5
    • Mac: Cmd + Shift + R

  2. Clear browser data:

    • Chrome: Settings → Privacy → Clear browsing data
    • Firefox: Settings → Privacy → Clear Data
    • Safari: Develop → Empty Caches

  3. Try incognito/private mode to verify it's a cache issue

Problem: "Module not found" errors

Solution: Python dependencies need updating:

cd /opt/openvox-gui
source venv/bin/activate
pip install --upgrade -r backend/requirements.txt
deactivate
sudo systemctl restart openvox-gui

Problem: Database errors after update

Solution: Run database migrations:

cd /opt/openvox-gui/backend
source ../venv/bin/activate
python -m alembic upgrade head
deactivate
sudo systemctl restart openvox-gui

Getting Update Help

If you're stuck:

  1. Check the update log:

    sudo journalctl -u openvox-gui --since "10 minutes ago"

  2. Verify file permissions:

    ls -la /opt/openvox-gui/
# Should be owned by puppet:puppet

  3. Test the configuration:

    cd /opt/openvox-gui
source venv/bin/activate
python -c "from backend.app.config import settings; print('Config OK')"
deactivate

  4. Ask for help:

    • Check GitHub Issues
    • Include your version, error messages, and what you tried

Version History

Understanding Version Numbers

OpenVox GUI uses Semantic Versioning (SemVer 2.0.0) plus optional pre-releases:

  • Stable: MAJOR.MINOR.PATCH (example: 3.10.6 — current stable on main)
  • Pre-release / beta trains: e.g. 3.10.6, 3.10.3b14, 3.9.0-dev.42, historical alpha labels such as 3.10.04.a8 on feature branches
  • ovox CLI version always matches the GUI (root VERSION file) as of 3.7.3

Rules of thumb:

  • MAJOR — big changes that might break compatibility
  • MINOR — new features that are backwards compatible
  • PATCH — bug fixes and small improvements
  • Prefer the latest stable GitHub Release for production; use betas only on lab/test unless you mean to

Examples:

  • 3.10.4 → 3.10.6: GUI performance (Dashboard lean PDB extract, multi-worker uvicorn, graph-page SWR)
  • 3.10.2 → 3.10.4: Live fleet consistency + 3.10.3 beta train (Log Viewer, ENC, Inventory, export, Executive Summary)
  • 3.10.3b14 → 3.10.4: Beta train promoted to stable (same code family)
  • 3.9.7 → 3.10.2: Feature line promotion (Insights NOC, ops UI, Orchestration #38)
  • 1.4.8 → 2.0.0: Major new feature (LDAP authentication) — see CHANGELOG for historical detail

Recent Versions

Version 3.10.6 (Current stable — July 2026)

  • Promotes 3.10.5-dev.1–dev.5 on main (GitHub Release)
  • Performance: Dashboard lean PuppetDB trend extract; multi-worker uvicorn (OPENVOX_GUI_UVICORN_WORKERS); API TTL caches; GZip; graph-page session SWR — see docs/PERFORMANCE.md
  • After upgrade: hard-refresh browsers once; confirm systemctl cat openvox-gui shows --workers N
  • Default git branch remains main (no staging branch)

Version 3.10.4 (stable — July 2026, superseded by 3.10.6 for new installs)

  • Promotes 3.10.3b1–b14 on main (GitHub Release)
  • Live fleet = active PuppetDB ∩ signed CA (get_live_nodes) for Nodes, Inventory, ENC, Dashboard, Node Health; ENC prunes SQLite ghosts
  • Nodes All Nodes export (CSV / JSON / text, column picker, respects filters)
  • Log Viewer Agent journal-first + identifier / host-journal fallbacks; sudoers -t rules
  • Purge / Bolt config / Executive Summary reliability fixes (see CHANGELOG)
  • After upgrade: open Classification (ENC) once so reconciliation runs; review sudoers backup if you used local overrides

Version 3.10.2 (stable — June 2026, superseded by 3.10.6 for new installs)

  • Promotes the 3.10 line on main after the 3.10.a_r_alpha.6 merge and 3.10.1.b1 / 3.10.1.b2 betas (GitHub Release)
  • Monitoring NOC multi-graph wallboard with shared UTC timeline; live JMX series timestamp fix
  • Ops UI — OpsTable, FilterBar, Insights hub (/insights, /insights/all)
  • Orchestration: one Bolt run per click (fixes triple execution — GitHub #38)

Version 3.10.1.b2 (beta, superseded by 3.10.2 / 3.10.4 / 3.10.6)

  • Orchestration single-run fix only (#38); prefer upgrading to 3.10.6

Version 3.7.0

  • Metrics / Insights section — visualization pages: Run Performance (JMX), Fleet Compliance, Fleet Fact Overview, Catalog Graph (React Flow), PuppetDB Health, Change Timeline, Environment Comparison, Node Heatmap, Classification Tree, Class Coverage
  • Certificate Audit tool for finding/cleaning orphaned CA certs
  • Navigation and chart polish; server-side caching (30s TTL) for expensive PuppetDB queries
  • Maintenance program foundations (ovox maintenance, branded maintenance pages)

Version 3.6.6

  • SSL Certificate Wizard — guided web certificate and Puppet CA intermediate workflows
  • Unclassified Nodes pane on Classification page now always visible
  • Security & maintenance: dependency updates, sqlite3 crash fix, sudoers hardening

Version 3.6.5

  • Node Scope filter on Fact Explorer (ENC group chip bar with multi-select)
  • "All Nodes" chip for clearing group filters

Version 3.6.4

  • Unclassified Nodes panel on the Nodes page
  • Purge Node button on Node Detail (PuppetDB + ENC + CA removal)
  • PuppetDB certname validation for ENC operations
  • Fact Explorer sorting, operator filtering, and row limiting

Version 3.6.0

  • OpenVox Agent Installer with local package mirror
  • Webhook HMAC security hardening
  • Per-subcommand sudoers rules replacing CA wildcards
  • Fernet-encrypted LDAP bind password at rest

Version 3.3.0

  • Orchestration targets resolved from PuppetDB in real-time instead of static inventory
  • Deploy health checks use HTTPS when SSL is enabled (fixes false "not healthy" errors)
  • Native SSL support on port 4567 with Puppet certs; SSL Configuration tab
  • Reports grouped by ENC node groups; broader navigation foundations

Version 2.3.x

  • Zero CVEs — all dependencies audited and upgraded (FastAPI 0.135.1, PyJWT 2.12.1)
  • python-jose replaced with PyJWT (eliminates unfixable ecdsa CVE)
  • Run OpenVox output panel on Node Detail page
  • ENC groups in Orchestration target selector
  • r10k deploy wrapper for proper environment reconstruction
  • Clone-then-deploy update architecture (scripts + documentation)
  • SUDOERS.md configuration guide

Version 2.0.x–2.2.x

  • LDAP / Active Directory split authentication
  • Per-user authentication source selection (local or LDAP)
  • Auto-provisioning of LDAP users on first login
  • Installer proxy support for corporate environments
  • Node.js auto-installation from system repos
  • Comprehensive security headers and rate limiting

Version 1.4.x

  • Fixed "Run OpenVox" button (uses bolt command run instead of missing task)
  • All Dependabot security alerts resolved
  • Python upgraded from 3.9 to 3.11 on production servers
  • Ghost user prevention (username whitespace stripping)
  • Centralized version management (single VERSION file)
  • User deletion bug fix; comprehensive security headers and rate limiting

Version 1.4.0 (First Production Release)

  • Production-ready release with comprehensive documentation
  • Graceful handling of application updates during deployments
  • Enhanced Fact Explorer with nested fact support
  • Comprehensive CA information panel
  • Many bug fixes and stability improvements

Version 0.3.x

  • Certificate Authority management (sign/revoke/clean)
  • Fact Explorer, Resource Explorer, PQL Console
  • Theme system (Casual dark mode / Formal light mode)
  • Orchestration with Bolt integration
  • Hierarchical Node Classifier (4-layer deep merge)

See the full Changelog for complete version history.

Best Practices for Updates

Do's ✅

  1. Always backup first - It takes 1 minute and can save hours
  2. Read release notes - Know what's changing
  3. Update regularly - Small frequent updates are easier than big jumps
  4. Test after updating - Click through main features to verify
  5. Keep update logs - Note when and what you updated

Don'ts ❌

  1. Don't skip major versions - Update incrementally (1.2 → 1.3 → 1.4)
  2. Don't update during peak hours - Users might be affected
  3. Don't ignore errors - Fix problems before they get worse
  4. Don't modify core files - Your changes will be lost on update
  5. Don't forget to clear browser cache - Causes confusion

Automated Update Notifications

OpenVox GUI can notify you when updates are available:

  1. In the Web Interface:

    • A banner appears when a new version is available
    • Click "View Update" to see what's new

  2. Email Notifications (coming soon):

    • Get emailed when updates are released
    • Configure in Settings → Notifications

  3. Check Manually:

    cd ~/openvox-gui
git fetch
git log HEAD..origin/main --oneline
# Shows commits available to pull

Security Updates

Security updates are released as needed and should be applied immediately:

  1. Identify security updates:

    • Version numbers ending in .1, .2, etc. often indicate patches
    • Check release notes for "Security" labels
    • Subscribe to security announcements

  2. Apply security updates immediately:

    cd ~/openvox-gui
git pull origin main
sudo ./scripts/update_local.sh --security

  3. Verify the update:

    # Check version
curl -k https://localhost:4567/health

# Check logs for any issues
sudo journalctl -u openvox-gui -n 100

Remember: Regular updates keep your system secure and running smoothly. When in doubt, backup first and update during a maintenance window!

Need help? Check the Troubleshooting Guide or visit our GitHub page.

This document was created with the assistance of AI (Grok, xAI). All technical content has been reviewed and verified by human contributors.