mirror of
https://github.com/rcourtman/Pulse.git
synced 2026-09-24 20:22:53 +00:00
Pulse Monitor
a423d42402
- Updated MIGRATION_V3_TO_V4.md to clarify .env is optional - Fixed CONFIGURATION.md file locations section - Verified all other references are correct - Installation scripts correctly check for v3 .env files - Security warnings already appropriate
145 lines
5.2 KiB
Markdown
145 lines
5.2 KiB
Markdown
# Pulse v3 to v4 Migration Guide
|
|
|
|
## ⚠️ CRITICAL: Manual Migration Required
|
|
|
|
**Pulse v4 is a complete rewrite from Node.js to Go**. Due to fundamental architecture changes, automatic upgrades from v3 to v4 are not supported and will break your installation.
|
|
|
|
## 🚫 DO NOT Attempt These Actions
|
|
|
|
1. **DO NOT run auto-update** from v3 to v4
|
|
2. **DO NOT use the old Proxmox helper script** - it's still configured for v3
|
|
3. **DO NOT try to upgrade in-place** - the applications are completely different
|
|
|
|
## ✅ Recommended Migration Process
|
|
|
|
### Option 1: Fresh Installation (Recommended)
|
|
|
|
1. **Create a new LXC container or VM** for Pulse v4
|
|
```bash
|
|
# Create new container in Proxmox
|
|
pct create [VMID] local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst \
|
|
--hostname pulse-v4 \
|
|
--memory 1024 \
|
|
--cores 1 \
|
|
--rootfs local-lvm:8 \
|
|
--net0 name=eth0,bridge=vmbr0,ip=dhcp
|
|
```
|
|
|
|
2. **Install Pulse v4** in the new container
|
|
```bash
|
|
# Download and run the v4 installer
|
|
wget https://raw.githubusercontent.com/rcourtman/Pulse/main/install.sh
|
|
chmod +x install.sh
|
|
./install.sh
|
|
```
|
|
|
|
3. **Configure your nodes** through the new web UI (port 7655)
|
|
- Add your Proxmox VE nodes
|
|
- Add your PBS instances (if applicable)
|
|
- Configure notifications (Discord, email, etc.)
|
|
- Set up alert thresholds
|
|
|
|
4. **Reference your old configuration** if needed
|
|
- Check your v3 `.env` file for API tokens and credentials
|
|
- Note your notification webhook URLs
|
|
- Document your alert threshold preferences
|
|
|
|
5. **Test thoroughly** before decommissioning v3
|
|
- Verify all nodes are being monitored
|
|
- Test alert notifications
|
|
- Ensure backups are visible (if using PBS)
|
|
|
|
6. **Shut down the old v3 instance** once v4 is working
|
|
|
|
### Option 2: Docker Migration
|
|
|
|
If you were using Docker for v3, the process is simpler:
|
|
|
|
1. **Stop and backup your v3 container**
|
|
```bash
|
|
docker stop pulse-v3
|
|
docker rename pulse-v3 pulse-v3-backup
|
|
```
|
|
|
|
2. **Run Pulse v4 with Docker**
|
|
```bash
|
|
docker run -d \
|
|
--name pulse \
|
|
-p 7655:7655 \
|
|
-v pulse-data:/data \
|
|
rcourtman/pulse:latest
|
|
```
|
|
|
|
3. **Configure through the web UI** at http://localhost:7655
|
|
- All node configuration is done through the UI
|
|
- No environment variables needed for Proxmox credentials
|
|
|
|
## 📋 Configuration Reference
|
|
|
|
### Environment Variables (v3 → v4)
|
|
|
|
**Important**: v4 does NOT use environment variables for node configuration. All configuration is done through the web UI.
|
|
|
|
| v3 Variable | v4 Equivalent | Notes |
|
|
|------------|---------------|-------|
|
|
| `PROXMOX_HOST` | UI Configuration | Settings → Nodes → Add Node |
|
|
| `PROXMOX_USER` | UI Configuration | Settings → Nodes → Add Node |
|
|
| `PROXMOX_PASSWORD` | UI Configuration | Encrypted storage via UI |
|
|
| `PROXMOX_TOKEN_ID` | UI Configuration | Split into name/value in UI |
|
|
| `PROXMOX_TOKEN_SECRET` | UI Configuration | Token auth recommended |
|
|
| `DISCORD_WEBHOOK` | UI Configuration | Settings → Notifications |
|
|
| `EMAIL_*` | UI Configuration | Settings → Notifications |
|
|
|
|
The only environment variable v4 supports is `PULSE_DATA_DIR` for Docker deployments to specify the data directory.
|
|
|
|
### Key Differences
|
|
|
|
1. **Port Change**: v3 used port 3000, v4 uses port **7655**
|
|
2. **No Node.js**: v4 is a Go binary, no npm/node required
|
|
3. **New UI**: Complete redesign with dark mode support
|
|
4. **Multi-node**: v4 supports multiple PVE/PBS instances natively
|
|
5. **Better Performance**: Significantly faster and lower resource usage
|
|
|
|
## 🔧 Troubleshooting
|
|
|
|
### "Missing package.json" Error
|
|
This means you're trying to run v4 with v3 startup scripts. Solution:
|
|
- Use the new systemd service file
|
|
- Don't use npm commands
|
|
- Run the binary directly: `/opt/pulse/pulse`
|
|
|
|
### Port 3000 Not Working
|
|
v4 uses port 7655 by default. Update your firewall rules and bookmarks.
|
|
|
|
### Can't Find .env File
|
|
v4 stores configuration through the web UI. Environment variables can be used for deployment overrides but are not required.
|
|
|
|
### Credentials Not Working
|
|
v4 has its own authentication system. Default credentials on fresh install:
|
|
- No authentication by default
|
|
- Set up security mode in Settings → Security
|
|
|
|
### No Configuration Export/Import
|
|
**By Design**: v4 does NOT support configuration export/import for security reasons:
|
|
- Proxmox API tokens with write permissions are stored encrypted
|
|
- These tokens can access/modify your infrastructure
|
|
- Export functionality would create a security vulnerability
|
|
- Each Pulse instance maintains its own isolated credential store
|
|
|
|
**Best Practice**: Document your configuration separately (node names, thresholds) but re-enter credentials manually for each instance.
|
|
|
|
## 📚 Additional Resources
|
|
|
|
- [Pulse v4 Release Notes](https://github.com/rcourtman/Pulse/releases/tag/v4.0.0)
|
|
- [Pulse v4 Documentation](https://github.com/rcourtman/Pulse#readme)
|
|
- [Report Issues](https://github.com/rcourtman/Pulse/issues)
|
|
|
|
## ⚡ Quick Start After Migration
|
|
|
|
1. Access the web UI at `http://your-server:7655`
|
|
2. Click Settings → Nodes → Add Node
|
|
3. Enter your Proxmox credentials
|
|
4. Configure notifications if desired
|
|
5. Customize alert thresholds as needed
|
|
|
|
Remember: v4 is a complete rewrite with many improvements. Take time to explore the new features! |