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/`)

```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
# 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
```

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
sudo chmod +x /opt/nupst/nupst
```

### Issue: Service won't start after migration

**Solution**: Systemd service file may reference old paths

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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](./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! 🎉