nupst/MIGRATION.md

Migration Guide: NUPST v3.x to v4.0

This guide will help you migrate from NUPST v3.x (Node.js-based) to v4.0 (Deno-based with pre-compiled binaries).

Overview

NUPST v4.0 is a complete architectural rewrite:

• Runtime: Node.js → Deno
• Distribution: Git repository + npm packages → Pre-compiled binaries
• Installation: Clone + setup.sh → Download binary
• Dependencies: Node.js + npm packages → Zero dependencies (self-contained binary)
• CLI Structure: Flat commands → Subcommand structure (with backward compatibility)

Good news: Your configuration files are 100% compatible - no changes needed!

Pre-Migration Checklist

Before migrating, gather this information:

1. Current version: Run nupst --version or check /opt/nupst/
2. Service status: Run nupst status to verify service is running
3. Configuration backup: Copy /etc/nupst/config.json to a safe location
4. Current installation: Note where NUPST is installed (usually /opt/nupst/)

# Backup your configuration
sudo cp /etc/nupst/config.json ~/nupst-config-backup.json

# Check current status
nupst status

# Note your version
nupst --version  # or cat /opt/nupst/package.json | grep version

Migration Steps

Step 1: Stop and Disable v3.x Service

# Stop the running service
sudo nupst stop

# Disable the service (removes from systemd)
sudo nupst disable

# Verify service is stopped
sudo systemctl status nupst  # Should show "inactive" or "not found"

Step 2: Remove v3.x Installation

The v4.0 installer will replace files, but it's cleaner to remove the old installation first:

# Remove the symlink
sudo rm /usr/local/bin/nupst

# Remove the installation directory
sudo rm -rf /opt/nupst

# Configuration at /etc/nupst/ is preserved
# DO NOT remove /etc/nupst/config.json

Step 3: Install NUPST v4.0

Use the new binary-based installer:

# Method 1: Download and run (recommended)
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh -o nupst-install.sh
sudo bash nupst-install.sh
rm nupst-install.sh

# Method 2: One-line installation
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash -s -- -y

The installer will:

• Auto-detect your platform (Linux x64/ARM64, macOS Intel/ARM, Windows)
• Download the appropriate pre-compiled binary
• Install to /opt/nupst/nupst
• Create symlink at /usr/local/bin/nupst

Step 4: Verify Installation

# Check version (should show 4.0.0 or higher)
nupst --version

# Verify configuration is intact
nupst config show

# Test UPS connectivity
nupst ups test

Step 5: Update CLI Commands (Optional)

v4.0 uses a new subcommand structure, but old commands still work with deprecation warnings.

You can update your scripts gradually:

Old (v3.x) → New (v4.0) Command Mapping:

v3.x Command	v4.0 Command	Status
nupst enable	nupst service enable	Old works with warning
nupst disable	nupst service disable	Old works with warning
nupst start	nupst service start	Old works with warning
nupst stop	nupst service stop	Old works with warning
nupst status	nupst service status	Old works with warning
nupst logs	nupst service logs	Old works with warning
nupst add	nupst ups add	Old works with warning
nupst edit [id]	nupst ups edit [id]	Old works with warning
nupst delete <id>	nupst ups remove <id>	Old works with warning
nupst list	nupst ups list	Old works with warning
nupst test	nupst ups test	Old works with warning
nupst group add	nupst group add	Unchanged
nupst group edit <id>	nupst group edit <id>	Unchanged
nupst group delete <id>	nupst group remove <id>	Changed
nupst group list	nupst group list	Unchanged
nupst config	nupst config show	Old works with warning
nupst update	Re-run installer	Removed
nupst uninstall	Manual removal	Removed

New aliases in v4.0:

• nupst ls → nupst ups list
• nupst rm <id> → nupst ups remove <id>

Step 6: Enable and Start Service

# Enable systemd service
sudo nupst service enable

# Start the service
sudo nupst service start

# Check status
nupst service status

# View logs
nupst service logs

Step 7: Verify Operation

# Check UPS status
nupst service status

# View recent logs
nupst service logs

# Verify daemon is monitoring
sudo journalctl -u nupst -n 20

Configuration Compatibility

What Stays the Same

✅ Configuration file format: /etc/nupst/config.json remains identical

✅ All SNMP settings: host, port, community, version, security levels, etc.

✅ UPS device configurations: All device IDs, names, thresholds, groups

✅ Group configurations: Redundant/non-redundant modes, descriptions

✅ Supported UPS models: CyberPower, APC, Eaton, TrippLite, Liebert, custom OIDs

What Changes

❌ Installation method: No more git clone, use binary installer

❌ Update process: Re-run installer instead of nupst update

❌ Uninstall process: Manual removal instead of nupst uninstall

❌ Systemd service path: ExecStart now points to binary instead of wrapper script

Troubleshooting Migration Issues

Issue: nupst: command not found

Solution: Symlink wasn't created or isn't in PATH

# Verify symlink exists
ls -la /usr/local/bin/nupst

# If missing, create manually
sudo ln -sf /opt/nupst/nupst /usr/local/bin/nupst

# Or add binary location to PATH
export PATH="/opt/nupst:$PATH"

Issue: Permission denied when running nupst

Solution: Binary isn't executable

sudo chmod +x /opt/nupst/nupst

Issue: Service won't start after migration

Solution: Systemd service file may reference old paths

# Check service file
sudo systemctl cat nupst

# If it references old paths, re-enable service
sudo nupst service disable
sudo nupst service enable
sudo nupst service start

Issue: Configuration not found

Solution: Configuration may have been accidentally deleted

# Restore from backup
sudo cp ~/nupst-config-backup.json /etc/nupst/config.json

# Or re-create configuration
sudo nupst ups add

Issue: Old commands show deprecation warnings

This is expected behavior. Old commands still work but will show:

Note: 'nupst enable' is deprecated. Use 'nupst service enable' instead.

To remove warnings, update to the new command syntax (see Step 5 above).

Issue: Binary won't execute (macOS)

Solution: macOS Gatekeeper may block unsigned binaries

# Remove quarantine attribute
xattr -d com.apple.quarantine /opt/nupst/nupst

# Or right-click and "Open" in Finder

Issue: Wrong architecture binary downloaded

Solution: Installer detected wrong platform

# Check your architecture
uname -m  # Should show: x86_64 (x64) or aarch64/arm64 (ARM)

# Download correct binary manually
# For Linux x64:
curl -sSL https://code.foss.global/serve.zone/nupst/releases/download/v4.0.0/nupst-linux-x64 -o nupst
sudo mv nupst /opt/nupst/nupst
sudo chmod +x /opt/nupst/nupst

Rollback to v3.x

If you need to rollback to v3.x:

# Stop v4.0 service
sudo nupst service stop
sudo nupst service disable

# Remove v4.0 installation
sudo rm /usr/local/bin/nupst
sudo rm -rf /opt/nupst

# Reinstall v3.x using old method
cd /tmp
git clone https://code.foss.global/serve.zone/nupst.git -b main /opt/nupst
cd /opt/nupst
git checkout v3.1.2  # Or your previous version
sudo ./install.sh -y

# Your configuration at /etc/nupst/config.json will still work

Post-Migration Best Practices

Update Automation Scripts

If you have scripts or automation that call NUPST:

# Update cron jobs, monitoring scripts, etc.
# Old: nupst status
# New: nupst service status

# Example crontab update:
# OLD: 0 * * * * /usr/local/bin/nupst status >> /var/log/nupst-check.log
# NEW: 0 * * * * /usr/local/bin/nupst service status >> /var/log/nupst-check.log

Monitor for Issues

Keep an eye on logs for the first few days:

# Real-time monitoring
nupst service logs

# Check for errors
sudo journalctl -u nupst --since "1 hour ago" | grep -i error

Update Documentation

Update any internal documentation to reflect:

• New installation method (binary-based)
• New CLI command structure
• New update process (re-run installer)

Benefits of v4.0

After migration, you'll enjoy:

✅ Faster Startup: Binary starts in milliseconds vs seconds

✅ Zero Dependencies: No Node.js or npm on the system

✅ Easier Updates: curl | bash vs git pull && npm install

✅ Better Security: No npm supply chain risks, checksums provided

✅ Smaller Footprint: ~340MB binary vs ~500MB+ (repo + Node.js + node_modules)

✅ Official Support: Pre-compiled binaries for all major platforms

✅ Automated Releases: New versions built and tested automatically

Need Help?

• Issues: https://code.foss.global/serve.zone/nupst/issues
• Documentation: https://code.foss.global/serve.zone/nupst
• Changelog: See changelog.md for detailed v4.0 changes

Migration Checklist

Use this checklist to track your migration:

• Backup configuration file
• Note current version and status
• Stop v3.x service (nupst stop)
• Disable v3.x service (nupst disable)
• Remove old installation
• Run v4.0 installer
• Verify version (nupst --version)
• Test configuration (nupst config show)
• Test UPS connectivity (nupst ups test)
• Enable v4.0 service (nupst service enable)
• Start v4.0 service (nupst service start)
• Verify service status (nupst service status)
• Monitor logs for issues (nupst service logs)
• Update automation scripts (optional)
• Update documentation (optional)

Welcome to NUPST v4.0! 🎉