migration/deno-v4 #1
377
MIGRATION.md
377
MIGRATION.md
@@ -1,377 +0,0 @@
|
||||
# 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! 🎉
|
||||
@@ -362,7 +362,7 @@ if [ $OLD_NODE_INSTALL -eq 1 ]; then
|
||||
echo " • CLI commands now use subcommand structure"
|
||||
echo " (old commands still work with deprecation warnings)"
|
||||
echo ""
|
||||
echo "Migration guide: https://code.foss.global/serve.zone/nupst/src/branch/main/MIGRATION.md"
|
||||
echo "See readme for migration details: https://code.foss.global/serve.zone/nupst#migration-from-v3x"
|
||||
echo ""
|
||||
fi
|
||||
|
||||
|
||||
90
readme.md
90
readme.md
@@ -435,18 +435,88 @@ sha256sum -c SHA256SUMS.txt --ignore-missing
|
||||
|
||||
## Migration from v3.x
|
||||
|
||||
If you're upgrading from NUPST v3.x (Node.js-based), see [MIGRATION.md](./MIGRATION.md) for detailed migration instructions.
|
||||
If you're upgrading from NUPST v3.x (Node.js-based) to v4.0 (Deno-based), the migration is straightforward using the install.sh script.
|
||||
|
||||
**Key Changes in v4.0:**
|
||||
- Powered by Deno instead of Node.js
|
||||
- Distributed as pre-compiled binaries
|
||||
- New subcommand structure (backward compatible)
|
||||
- Zero dependencies required
|
||||
- Smaller installation footprint
|
||||
- Faster startup and execution
|
||||
### Quick Migration
|
||||
|
||||
**Configuration Compatibility:**
|
||||
Your existing `/etc/nupst/config.json` from v3.x is fully compatible with v4.0. No changes required.
|
||||
The installer script automatically handles the entire migration while preserving your configuration:
|
||||
|
||||
```bash
|
||||
# Run the installer (handles stop/update/restart automatically)
|
||||
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash -s -- -y
|
||||
|
||||
# Verify
|
||||
nupst service status
|
||||
```
|
||||
|
||||
**That's it!** The installer automatically:
|
||||
- Detects your v3.x installation
|
||||
- Stops the running service
|
||||
- Replaces the binary with v4.0
|
||||
- Restarts the service
|
||||
- Preserves your `/etc/nupst/config.json` (fully compatible, no changes needed)
|
||||
|
||||
### Key Changes in v4.0
|
||||
|
||||
- **Runtime**: Node.js → Deno
|
||||
- **Distribution**: Git repository + npm packages → Pre-compiled binaries
|
||||
- **Installation**: Clone + setup.sh → Download binary via install.sh
|
||||
- **Dependencies**: Node.js + npm packages → Zero dependencies (self-contained binary)
|
||||
- **CLI Structure**: Flat commands → Subcommand structure (backward compatible)
|
||||
- **Updates**: `nupst update` → Re-run install.sh
|
||||
- **Footprint**: Single ~340MB self-contained binary (vs repo + node_modules in v3.x)
|
||||
- **Startup**: Seconds → Milliseconds
|
||||
|
||||
### Command Mapping
|
||||
|
||||
v4.0 uses a new subcommand structure, but **old commands still work** with deprecation warnings:
|
||||
|
||||
| v3.x Command | v4.0 Command | Notes |
|
||||
|-------------|--------------|-------|
|
||||
| `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 config` | `nupst config show` | Old works with warning |
|
||||
|
||||
**New aliases:** `nupst ls` (list UPS devices), `nupst rm <id>` (remove UPS device)
|
||||
|
||||
### Configuration Compatibility
|
||||
|
||||
✅ **Fully Compatible:**
|
||||
- Configuration file format: `/etc/nupst/config.json`
|
||||
- All SNMP settings (host, port, community, version, security)
|
||||
- UPS device configurations (IDs, names, thresholds, groups)
|
||||
- Group configurations (redundant/non-redundant modes)
|
||||
- Supported UPS models (CyberPower, APC, Eaton, TrippLite, Liebert, custom OIDs)
|
||||
|
||||
### Troubleshooting Migration
|
||||
|
||||
**Service won't start after migration:**
|
||||
```bash
|
||||
# Re-enable service to update systemd file
|
||||
sudo nupst service disable
|
||||
sudo nupst service enable
|
||||
sudo nupst service start
|
||||
```
|
||||
|
||||
**Binary won't execute:**
|
||||
```bash
|
||||
sudo chmod +x /opt/nupst/nupst
|
||||
```
|
||||
|
||||
**Command not found:**
|
||||
```bash
|
||||
# Recreate symlink
|
||||
sudo ln -sf /opt/nupst/nupst /usr/local/bin/nupst
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
|
||||
@@ -13,8 +13,11 @@ echo ""
|
||||
echo "Compiling for all supported platforms..."
|
||||
echo ""
|
||||
|
||||
# Create binary directory
|
||||
# Clean up old binaries and create fresh directory
|
||||
rm -rf "$BINARY_DIR"
|
||||
mkdir -p "$BINARY_DIR"
|
||||
echo "→ Cleaned old binaries from $BINARY_DIR"
|
||||
echo ""
|
||||
|
||||
# Linux x86_64
|
||||
echo "→ Compiling for Linux x86_64..."
|
||||
|
||||
Reference in New Issue
Block a user